外部 Agent MCP 連携

信頼できるサーバー側アプリケーションから Manager AGI Agent を MCP ツールとして利用します。このガイドでは設定、認証、下流認可、呼び出し、復旧、安定したエラー契約を説明します。

クイックスタート

Web 管理画面で有効なサードパーティアプリケーションを作成し、会社を関連付け、App ID と App Secret を取得します。
有効で公開済み Skill を持つ Agent を会社に割り当てます。
MCP Streamable HTTP クライアントを Engine の HTTPS ホストにある POST|GET|DELETE /openapi/v1/agents/mcp へ接続します。
初期化後に notifications/initialized、tools/list、agent_{id} の順に送信します。

汎用アシスタントは公開されません。Secret はサーバーだけに保持してください。

認証と権限範囲

API 環境：

テスト環境：https://aim-api-test.proton-system.com
本番環境：https://aim-api.proton-system.com

すべてのリクエストに次のヘッダーが必要です。

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

カスタムリクエストヘッダーに対応するリモート MCP クライアントでは、次の設定を使用できます。

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

有効なアプリケーションには会社単位の恒久的な承認が与えられます。現在または将来割り当てる Agent と新しく公開する Skill は、書き込みや高リスク操作を含め、人の承認なしで直ちに利用可能になります。CompanyRole はこの権限を制限しません。Engine は引き続き状態、割り当て、公開、下流認可、スキーマ/リスク変化、検証、制限、冪等性、監査を確認します。

初期化とセッション

初期化し、応答ヘッダー Mcp-Session-Id を保存します。

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

以後の POST、GET、DELETE に Mcp-Session-Id を付けます。INVALID_MCP_SESSION の後は再初期化します。

Agent ツールとメタデータ

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

ツール名は agent_{id} で、接頭辞の後には完全な Agent ID が入ります。トップレベルの title は Agent 名、description は Agent の説明（空の場合は名前）です。_meta.easyposAgent は公開情報の id、name、description、iconUrl のみを含みます。authorizationRequirements には mcpHubId、mcpHubName、authType、status、expiresAt、authorized と、認可が必要な場合に Engine が生成する authorizationUrl が含まれます。プロンプト、クイック質問、Skill 定義、内部スキーマ、資格情報は公開されません。

下流認可

status が MISSING または REAUTH_REQUIRED の場合、Engine が生成した authorizationUrl を開きます。パスは /openapi/v1/mcp/authorization/start で始まります。ユーザーが認可を完了した後、アプリは tools/list または元の tools/call を再試行します。ACTIVE は Engine がアプリスコープで保存した認可を使って実行できる状態です。期限切れまたは下流の 401 では同じフローをやり直します。トークン更新、下流ヘッダー送信、失敗した業務呼び出しの自動再実行は行いません。

Agent の呼び出し

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"本日の未処理注文を要約してください","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId は必須で前後空白を除き 128 UTF-8 バイトまで、message は必須で 16 KiB までです。conversationId は任意で、同じアプリケーション、会社、Agent だけが再利用できます。標準 MCP 進捗には _meta.progressToken を指定します。

成功結果には "status":"COMPLETED"、"answer"、requestId、conversationId、表示メタデータ、authorizationRequirements が含まれます。下流資格情報が不足すると isError:true、status:"authorization_required"、errorCode:"MCP_AUTHORIZATION_REQUIRED" を返し、実行を作成しません。

SSE、再開、キャンセル、終了

MCP 進捗と最終結果を受信します。切断後は Basic 認証に加え、Mcp-Session-Id、不透明な Last-Event-ID、EasyPOS-Agent-Request-Id、EasyPOS-Agent-Id、Accept: text/event-stream を付けて GET します。再生は Agent を再実行しません。残りがあれば新しいカーソルで GET を繰り返します。

明示的な MCP キャンセルはキャンセルを要求するだけで、送信済みの副作用は戻りません。transport disconnect では受理済み処理はキャンセルされません。Basic と Mcp-Session-Id を付けた DELETE で終了します。

制限と冪等性

境界	契約
入力	`requestId` 128 bytes、`message` 16 KiB、POST 256 KiB
呼び出し	Agent MCP は呼び出し頻度を制限しません。会話 lease、冪等性、入力サイズの制約は適用されます
保持	冪等性と再生を 90 日保持
イベント	256 件保存、GET 1 回につき 64 件

requestId はアプリケーション内で 90 日間冪等です。同一入力は実行枠を追加消費せず結果を再生します。異なる入力は IDEMPOTENCY_CONFLICT、実行中は REQUEST_IN_PROGRESS になる場合があります。

エラー契約

トランスポートエラーは HTTP と {"code":"COMPANY_INACTIVE","description":"The company is inactive."} のような JSON を使います。MCP/ドメインエラーは isError:true、errorCode、errorDescription を返します。説明は安定した非機密の英語であり、プログラムはコードで分岐してください。

コード	返される説明
`INVALID_APP_CREDENTIALS`	The application credentials are missing or invalid.
`APPLICATION_INACTIVE`	The third-party application is inactive.
`COMPANY_INACTIVE`	The company is inactive.
`AGENT_NOT_FOUND`	The Agent does not exist.
`AGENT_NOT_ASSIGNED`	The Agent is not assigned to this company.
`AGENT_DISABLED`	The Agent is disabled.
`INVALID_AGENT_REQUEST`	The Agent request input is missing or exceeds the supported limits.
`CONVERSATION_BUSY`	The conversation already has an active execution.
`CONVERSATION_SCOPE_MISMATCH`	The conversation does not belong to this application, company, or Agent.
`MCP_AUTHORIZATION_REQUIRED`	Required downstream MCP authorization is missing.
`MCP_AUTHORIZATION_EXPIRED`	The downstream MCP authorization has expired.
`INVALID_MCP_SESSION`	The MCP session is missing, invalid, expired, or outside the application scope.
`EVENT_CURSOR_SCOPE_MISMATCH`	The event cursor does not belong to the requested application, Agent, or request scope.
`EVENT_REPLAY_UNAVAILABLE`	The requested event replay is no longer available.
`ORIGIN_NOT_ALLOWED`	The request origin is not allowed for this application.
`IDEMPOTENCY_CONFLICT`	The requestId was already used with different input.
`REQUEST_IN_PROGRESS`	The idempotent request is still in progress.
`SCHEMA_OR_RISK_DRIFT`	A Tool schema or execution-risk change requires refreshed metadata.
`REQUEST_CANCELLED`	The Agent request was cancelled or exceeded its deadline.
`AGENT_REQUEST_FAILED`	The previously recorded Agent request failed.
`AGENT_EXECUTION_FAILED`	The Agent execution failed without a safe public detail.

セキュリティとトラブルシューティング

TLS とシークレット管理を使い、ログから認証ヘッダーを除外します。ブラウザー、モバイル、URL、リポジトリに App Secret を置かないでください。サーバークライアントは Origin を省略し、送る場合は許可済みの HTTPS Origin にします。漏えい時はアプリケーションを無効化するか Secret を再設定します。

tools/list が空なら会社/Agent の状態、割り当て、公開済み Skill を確認します。認可が必要なら authorizationUrl を開き、完了後に検出または呼び出しを再試行します。無効なセッションは再初期化します。通知用 callbackUrl は Agent 結果の宛先ではなく、結果は MCP/SSE から読み取ります。