エージェントに報告と質問を。

01はじめる前に

Pushyouモバイルアプリでアカウントと会話を作成してください。WebログインにはアプリでのQR承認が必要です。接続設定で会話を選び、実際の配信を確認できます。

OAuthでは承認時に会話と権限を選択し、別のAPIキーは必要ありません。プログラムキーは設定 → 接続管理で作る別の認証方法です。新しい会話の作成には全会話へのアクセスとconversations:writeが必要です。

02認証

Streamable HTTPサーバーです。OAuthではクライアントが承認画面を開きます。Pushyouで会話と権限を確認して承認してください。プログラムキーにも同じ範囲確認が適用されます。OAuthとBearerキーの設定は混在させないでください。

https://pushyou.app/mcp

~/.codex/config.tomlにサーバーを追加し、codex mcp login pushyouを実行します。OAuthを使うには既存のPushyouのBearerキー設定を削除してください。アプリやIDEのMCP認証ボタンも使えます。

[mcp_servers.pushyou]
url = "https://pushyou.app/mcp"

03実際のメッセージと返信で確認

最初にpushyou_get_accountとpushyou_list_conversationsを呼び出します。アカウント、権限、会話を確認してから送信します。YOUR_CONVERSATION_IDを実際の値に置き換えてください。例はREST本文ではなくMCPツールの引数です。

{}

{
  "limit": 20
}

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "id": "docs-mcp-message-01",
  "text": "Pushyou connection verified.",
  "notify": true
}

Pushyouで返信した後、pushyou_get_eventsを一度呼び出し、eventsとnext_cursorを確認します。ツールの成功だけでは端末への通知配信は確認できません。MCPの接続だけでエージェントが常時動作するわけでもありません。

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "after": 0
}

MCPの一覧ツールはlimit（1〜50、初期値20）とbeforeを、イベントはafterを使います。メッセージ一覧はカードの要約を返し、pushyou_get_messageで全文を取得できます。写真の原本や大きいファイルのバイト範囲にはpushyou_get_mediaを使います。

04質問と判断

選択・承認・不足している情報など、オーナーが決めることが出てきたらpushyou_askを呼び出します。質問を一度だけ送ってオーナーに通知し、wait_seconds（既定45秒）の間回答を待ちます。waitingが返ったら同じ引数でもう一度呼び出します。質問が重複して送られることはありません。以前の質問はpushyou_get_answerにIDを指定して確認します。回答はレシーバーではなく、質問したエージェントに届きます。

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "id": "docs-mcp-question-01",
  "question": "Refactor finished and **all tests pass**. Deploy to staging?",
  "options": [
    {
      "id": "deploy",
      "label": "Deploy"
    },
    {
      "id": "wait",
      "label": "Not yet"
    }
  ]
}

別のプログラムが実行する重要な作業は、質問ではなくタスクの承認を依頼します。繰り返し発生する種類にはdeploy-stagingのような固定のkindを付けます。同じkindを何度か承認すると、オーナーはモバイルアプリでその会話の常設ルールをオンにできます。以後、一致するタスクは1日の上限内で実行待ちとして作成され、オーナーはアプリまたはウェブでルールをオフにできます。レビューを前提にせず、返されたステータスを確認してください。

日常的な進捗にはpriority: lowを使います。これらのメッセージは即時通知されず、常設ルールで承認されたタスクと一緒にオーナーの1日のまとめに集計されます。質問と承認依頼はすぐに通知されます。

エージェントへの指示

プロジェクトのCLAUDE.mdまたはAGENTS.mdに次のような短い項目を加えると、エージェントがPushyouで報告・質問します。会話IDはご自身のものに置き換えてください。

## Pushyou
- Report meaningful results to the Pushyou conversation `YOUR_CONVERSATION_ID` with `pushyou_send_message`. Lead with the outcome; Markdown is rendered. Use `priority: "low"` for routine progress.
- When a decision is mine (approval, a choice between options, missing information), call `pushyou_ask` in that conversation with one clear question and short options, then continue with the answer. If it returns `waiting`, call it again with the same arguments. Do not guess on decisions that affect external systems.
- Never put credentials, tokens or private keys in messages.

05返信と業務の実行

アプリで返信してからイベントを取得します。通常の返信や操作を実際に処理した後、結果の保存、ACK、next_cursorの永続保存の順に進めます。ACKはイベント削除や排他的な実行権ではありません。通常の自動応答は会話ごとに1つのプログラムにするか、独自に調整してください。

タスクは承認と実行結果をまとめて追跡します。所有者の承認後、ワーカーはtask_protocol=1でイベントを取得し、実行トークンを永続保存してから試行を取得します。heartbeatで権利を維持し、実際の結果を保存してcompleteを送ります。完了時にイベントもACKされます。単独のACKでは未完了タスクを終了できません。

Webhooks

署名付きの応答Webhookも利用できます。モバイルアプリの応答Webhook設定で接続してください。元の本文の署名を検証し、配信IDで重複を除きます。HTTP 2xxは受信確認であり、タスク完了ではありません。署名と再試行の仕様は業務ガイドにあります。

06ファイルと会話の画面

MCPではpushyou_prepare_media_uploadにmedia_id、filename、content_type、バイト数、SHA-256を渡します。返されたupload.urlと専用ヘッダーをそのまま使い、5分以内に元のバイト列をPOSTしてからattachment_idsを送信します。RESTにも同じ準備APIがあります。アップロード権限をアカウントキーやMCP OAuthトークンに置き換えないでください。

pushyou_set_viewにreport、actions、htmlカードを渡して会話の画面を公開します。viewをnullにすると削除できます。画面は所有する会話から開きます。HTMLは外部ネットワーク、アプリの認証情報、ブラウザーの保存領域にアクセスできません。宣言した操作は同じ会話のイベントになります。

Card =
  { type: "report", title: string, items: { title: string, body?: string, label?: string }[] }
| { type: "actions", title: string, body?: string, actions: { id: ID, label: string }[] }
| { type: "html", title: string, html: string, height?: integer, actions?: { id: ID, label: string }[] }

Field = { id: ID, label: string, type: "text" | "multiline" | "number" | "date" | "select" | "checkbox", required?: boolean, options?: string[], min?: number, max?: number }

07ツール一覧

サーバーが対応するツールの一覧です。認証済みのtools/listは接続で許可されたツールと最新の入力スキーマのみを返します。会話へのアクセス範囲は呼び出すたびに確認されます。

08トラブルシューティング

RESTエラーは2xx以外のステータスと{"error": "…"}を返します。MCPのツールエラーはクライアントに表示されます。構造化されたエラーと接続権限を確認してください。