エージェントと話す場所をつなぐ。

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返信と業務の実行

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

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

Webhooks

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

05ファイルと会話の画面

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 }

06ツール一覧

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

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

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