

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# MCP プロトコル契約

エージェントがツールとエージェントサーバーを呼び出すことができるように、Amazon Bedrock AgentCore ランタイムにモデルコンテキストプロトコル (MCP) を実装するための要件を理解します。これらの要件は、コンピューティングタイプ、microVMs、インスタンスの両方の MCP [インスタンス](runtime-instances-how-it-works.md)サーバーに適用されます。

コード例については、[AgentCore ランタイムで MCP サーバーをデプロイする](runtime-mcp.md)」を参照してください。

**Topics**
+ [プロトコル実装要件](#protocol-implementation-requirements)
+ [サーバーの要件](#container-requirements-mcp)
+ [パスの要件](#path-requirements-mcp)
+ [ヘルスプローブ](#mcp-health-probes)
+ [エラー処理](#mcp-error-handling)
+ [OAuth 認証レスポンス](#mcp-oauth-authentication-responses)

## プロトコル実装要件
<a name="protocol-implementation-requirements"></a>

MCP サーバーは、以下の特定のプロトコル要件を実装する必要があります。
+  **トランスポート**: ストリーミング可能な HTTP トランスポートを使用します。バージョン `2025-11-25`以前では、デフォルトでステートレスモード () `stateless_http=True` を使用して、 AWSのセッション管理とロードバランシングとの互換性を確保します。バージョン `2026-07-28` 以降は MCP 仕様によってステートレスです。
+  **セッション管理** : プラットフォームは、 `Mcp-Session-Id`および を含むセッションヘッダー`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`を MCP サーバーに転送します。MCP サーバーは、これらのヘッダーを受け入れ、それらを含むリクエストを拒否しないようにする必要があります。

**ヒント**  
AgentCore Runtime はステートフル MCP サーバー () `stateless_http=False` もサポートしています。ステートフル MCP サーバーでは、誘発 (マルチターンユーザーインタラクション) やサンプリング (LLM 生成コンテンツ) などの機能を使用できます。MCP プロトコルバージョン `2025-11-25`以前では、サーバーがオープンセッションでこれらのリクエストを配信するため、誘発とサンプリングにはステートフルモードが必要です。バージョン `2026-07-28`以降では、誘発とサンプリングはマルチラウンドトリップリクエスト (MRTR) パターンを使用します。これはステートフルモードを必要としません。MRTR の詳細については、Model Context Protocol ドキュメントの[「マルチラウンドトリップリクエスト](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr)」を参照してください。  
ステートフルモードは、複数のリクエストにわたって MCP セッション内で状態を保持します。ステートレス MCP サーバーは、データベースなど、アプリケーションが管理するバッキングストアに状態を保持します。明示的な状態ハンドルを使用して、その状態を参照します。サーバーはツールの結果に状態識別子を返し、クライアントは後でキーを に呼び出すときにそれをストアに返します。明示的な状態ハンドルの詳細については、Model Context Protocol ドキュメントの[「明示的な状態ハンドル](https://modelcontextprotocol.io/seps/2567-sessionless-mcp#explicit-state-handles)」を参照してください。ステートフル MCP サーバーの詳細については、[「ステートフル MCP サーバー機能](mcp-stateful-features.md)」を参照してください。

### MCP セッション管理と microVM の維持
<a name="mcp-session-management"></a>

AgentCore ランタイムは、セッション ID に基づいて各リクエストをmicroVM にルーティングします。クライアントリクエストヘッダーからセッション ID を取得するか、リクエストにセッション ID が含まれていない場合はセッション ID を生成します。セッション ID が同じリクエストは、セッションがアクティブである間、同じmicroVM に送信されます。インスタンスでは、同じセッション ID を持つリクエストは同じインスタンスセッションに送られます。詳細については、[「エージェントに分離されたセッションを使用する](runtime-sessions.md)」および「インスタンスには[セッション](runtime-instances-how-it-works.md#runtime-instances-session)」を参照してください。関連するリクエストに同じセッション ID を送信すると、次のことに役立ちます。
+ リクエストごとに新しいセッションを開始するレイテンシーを回避します。
+ 関連するリクエストは、それぞれ新しいセッションを開始するのではなく、1 つのセッションを共有するため、コストを削減できます。
+ 各新しいセッションはそれに対してカウントされるため、アクティブなセッションのクォータ内にとどまります。詳細については、[「リソース割り当ての制限](bedrock-agentcore-limits.md#resource-allocation-limits)」を参照してください。
+ クライアントがポーリングする長時間実行されるタスクのステータスなど、リクエスト間でサーバーがメモリに保持する状態を維持します。

AgentCore Runtime がセッション ID に使用するヘッダーは、MCP プロトコルのバージョンによって異なります。バージョンは `Mcp-Session-Id`ヘッダー`2026-07-28`を削除するためです。詳細については、「MCP 2026-07-28 仕様の[キーの変更](https://modelcontextprotocol.io/specification/2026-07-28/changelog#major-changes)」を参照してください。

#### バージョン 2026-07-28 以降
<a name="mcp-microvm-stickiness-2026-07-28"></a>

AgentCore Runtime は、 をセッション ID `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`として使用します。下位互換性のために、引き続き を受け入れます`Mcp-Session-Id`。クライアントが両方のヘッダーを送信する場合、AgentCore ランタイムは を使用します`Mcp-Session-Id`。各レスポンスヘッダーは、2 つの値が異なっていても、クライアントが同じリクエストヘッダーで送信した値を返します。クライアントがヘッダーの 1 つだけを送信する場合、両方のレスポンスヘッダーはその値を使用します。クライアントがどちらも送信しない場合、どちらもサービスが生成するセッション ID を使用します。

**ヒント**  
リクエストを同じmicroVMに保持するには、リクエストごとに同じ`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`値を送信します。

#### バージョン 2025-11-25 以前
<a name="mcp-microvm-stickiness-legacy"></a>

AgentCore Runtime は、 をセッション ID `Mcp-Session-Id`として使用します (MCP 仕様については、[「MCP Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http)」を参照してください）。クライアントは、レスポンスで`Mcp-Session-Id`返された をキャプチャし、それ以降のすべてのリクエストに含める必要があります。サービスは、このバージョンのリクエストをルーティング`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`するために を使用しません。

 **ステートレス MCP** ( `stateless_http=True` ):
+ クライアントは独自の を送信するか`Mcp-Session-Id`、最初のリクエストでそれを省略して、AgentCore Runtime がレスポンスで返すようにすることができます。
+ クライアントは、microVM アフィニティの後続のすべてのリクエスト`Mcp-Session-Id`に同じ を含める必要があります。

 **ステートフル MCP** ( `stateless_http=False` ):
+ クライアントは、 `Mcp-Session-Id`ヘッダーなしで初期化リクエストを送信します。
+ プラットフォームはレスポンス`Mcp-Session-Id`で を返します。
+ クライアントは、セッション状態とmicroVM アフィニティの両方の後続のすべてのリクエスト`Mcp-Session-Id`にこれを含める必要があります。

ステートフル MCP セッション管理の詳細については、[「MCP セッション管理仕様](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management)」を参照してください。

## サーバーの要件
<a name="container-requirements-mcp"></a>

直接コードデプロイを使用するかコンテナイメージを使用するかにかかわらず、MCP サーバーは次の要件を満たしている必要があります。
+  **ホスト:** `0.0.0.0` 
+  **サービングポート**: `8000` デフォルトでは 、または のサービングポート `protocolConfiguration.port` 
+  **アーキテクチャ**: ARM64。コンテナイメージをデプロイする場合は、ARM64 用に構築します。直接コードデプロイを使用する場合は、ARM64 用のパッケージにネイティブバイナリを構築します。

でサービングポートと `InvokeAgentRuntime` POST パスを変更できます`protocolConfiguration`。「デフォルト[パスのパス要件](#path-requirements-mcp)」を参照してください。設定例については、[「エージェントのサービングポートと呼び出しパスを設定する](runtime-configure-invocation.md)」を参照してください。

## パスの要件
<a name="path-requirements-mcp"></a>

### /mcp - POST
<a name="mcp-endpoint"></a>

 **目的** 

MCP RPC メッセージを受信し、エージェントのツール機能を通じて処理します。標準の MCP RPC メッセージを使用して [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API ペイロードを完全にパススルーします。

 **レスポンスの形式** 

JSON-RPC ベースのリクエスト/レスポンス形式。 `application/json`と の両方をレスポンスコンテンツタイプ`text/event-stream`としてサポート

 **ユースケース** 

`/mcp` エンドポイントには、いくつかの重要な目的があります。
+ ツールの呼び出しと管理
+ エージェント機能検出
+ リソースのアクセスと操作
+ マルチステップエージェントワークフロー

### /ping - GET (推奨)
<a name="mcp-ping-endpoint"></a>

 **目的** 

サーバーが実装する MCP プロトコルバージョンとは無関係に、MCP サーバーが正常かどうかをレポートします。AgentCore ランタイムには は必要ありませんが`/ping`、すべての MCP サーバーに実装することをお勧めします。を使用すると`GET /ping`、サーバーはバックグラウンド作業の実行`HealthyBusy`中にレポートできるため、AgentCore Runtime はアイドル状態でセッションを終了しません。詳細については、[「ランタイムセッションライフサイクル管理](runtime-long-run.md#runtime-long-run-session-lifecycle)」を参照してください。

 **レスポンスの形式** 

検出するには、 が以下を実行`/ping`する必要があります。
+ MCP パスに関係なく、サーバーのサービングポート (デフォルトで`/ping`は) のルートパス (`8000`) で提供されます。
+ [HTTP プロトコル契約の /ping - GET ](runtime-http-protocol-contract.md#http-ping-endpoint)で説明されている形式の JSON 本文で`2xx`ステータスを返します。HTML ページや本文`200`が異なるキャッチオールなどの他のレスポンスは、`/ping`サポートとして扱われません。

## ヘルスプローブ
<a name="mcp-health-probes"></a>

AgentCore Runtime はサーバーをプローブして、トラフィックを処理する準備ができているタイミングと、トラフィックがまだ正常かどうかを判断します。推奨されるヘルスエンドポイントを実装するには、[「/ping - GET (推奨)](#mcp-ping-endpoint)」を参照してください。

### セッション開始時の準備状況チェック
<a name="mcp-readiness-probe"></a>

新しいセッションが開始されると、AgentCore Runtime はサーバーのサービングポート`GET /ping`に を送信します。`502` または 以外のレスポンス`429`は、サーバーが接続を受け入れたことを示します。これには、 `404`と が含まれます`405`。AgentCoreランタイムはサーバーを準備完了として扱います。サーバーが を実装していない場合`/ping`、アクセスログ`GET /ping`の `404 Not Found` for は想定され、無害です。

### セッション中のヘルスチェック
<a name="mcp-liveness-probe"></a>

サーバーが稼働した後も、AgentCore Runtime は引き続きヘルスチェックを行います。まず、サーバーが を実装しているかどうかをチェックします`GET /ping`。その場合、AgentCore Runtime は残りのセッション`GET /ping`に を使用します。それ以外の場合は、 という MCP `ping`リクエスト`POST`を JSON-RPC `ping`メソッドと `Accept: application/json, text/event-stream`ヘッダーを使用して MCP パスに送信します。このフォールバックは、ステートフルモードとステートレスモードの両方で MCP プロトコルバージョン `2025-11-25`以前のサーバーと、バージョン のサーバーをサポートします`2026-07-28`。

バージョンのサーバーでは、 `ping`メソッドと`initialize`ハンドシェイクが削除されたため、`ping`リクエストが拒否`2026-07-28`される場合があります。サーバーが HTTP を `400`に返す場合`ping`、AgentCore ランタイムは `initialize`リクエストを送信します。このリクエストが も返す場合`400`、AgentCore Runtime は応答を停止するか、サーバーエラーを返さない限り、サーバーを正常として扱います。また、 の実装を推奨する 1 回限りのメッセージをエージェントのログに書き込みます`/ping`。`ping` または へのその他のエラーレスポンス`initialize`は、ヘルスチェックに失敗する可能性があります。

**注記**  
MCP SDK、そのバージョン、および設定によって、サーバーが に応答するかどうかが決まります`ping`。現在のバージョンと以前のバージョンの両方をサポートする一部の SDKsは、プロトコルバージョンを指定しないクライアント`ping`から引き続き応答します。`2026-07-28` 以降のみをサポートする SDKsは拒否します。がない場合`GET /ping`、AgentCore ランタイムは、このようなサーバーが応答を停止したか、サーバーエラーなどの`ping`拒否以外のエラーを返していることのみを検出できます。AgentCore Runtime に信頼性の高いヘルスシグナルを提供するには、 を実装します`GET /ping`。

## エラー処理
<a name="mcp-error-handling"></a>

AgentCore Runtime は、JSON-RPC 2.0 エラーレスポンスとしてエラーを返します。エラーコードと HTTP ステータスコードは、`MCP-Protocol-Version`リクエストヘッダーによって異なります。
+  **バージョン `2026-07-28`以降**: HTTP ステータスコードは [MCP 2026-07-28 仕様](https://modelcontextprotocol.io/specification/2026-07-28)に合わせてエラーを反映します。
+  **バージョン `2025-11-25` 以前、またはヘッダーがないか無効**です: ほとんどのエラーは HTTP 200 を返します。認証、認可、および Accept ヘッダーエラーのみが、他のステータスコードを使用します。

次の表に、各ランタイム例外のエラーを示します。


| ランタイム例外 | HTTP エラーコード (2026-07-28 以降) | JSON-RPC エラーコード (2026-07-28 以降) | HTTP エラーコード (2025-11-25 以前) | JSON-RPC エラーコード (2025-11-25 以前) | エラーメッセージ | 
| --- | --- | --- | --- | --- | --- | 
| UnauthorizedException | 401 | -32001 | 401 | -32001 | 認証エラー - 無効な認証情報 | 
| AccessDeniedException | 403 | -20001 | 403 | -32002 | 認可エラー - アクセス許可が不十分 | 
| ThrottlingException | 429 | -32003 | 200 | -32003 | レート制限を超えました - リクエストが多すぎます | 
| ServiceQuotaExceededException | 429 | -32003 | 200 | -32003 | レート制限を超えました - リクエストが多すぎます | 
| ResourceNotFoundException | 404 | -32602 | 200 | -32004 | リソースが見つかりません - リクエストされたリソースは存在しません | 
| ConflictException | 409 | -32005 | 200 | -32005 | リソースの競合 - リソースが既に存在します | 
| RetryableConflictException | 409 | -32005 | 200 | -32005 | セッションオペレーションが進行中です。再試行してください | 
| ValidationException | 400 | -32006 | 200 | -32006 | 検証エラー - 無効なリクエストデータ | 
| RuntimeClientError | 424 | -32010 | 200 | -32010 | ツール実行エラー - 詳細については、CloudWatch ログを確認してください | 
| McpRequestUnacceptableException | 406 | -32011 | 406 | -32011 | Accept Header エラー - MCP プロトコルには Accept ヘッダーが必要です: application/json、text/event-stream | 
| その他の例外 | 500 | -32603 | 200 | -32603 | 内部エラー - サーバーエラー | 

**注記**  
バージョン `2026-07-28`以降では、 は `-20001`の代わりに JSON-RPC エラーコード`AccessDeniedException`を返します`-32002`。MCP 2026-07-28 仕様では、サーバーが を送信できないため`-32002`、新しいエラーコードでは JSON-RPC 予約範囲外の値 (`-32768` から ) を使用することをお勧めします`-32000`。HTTP ステータスコード (403) は同じままです。
バージョン `2026-07-28`以降では、 は の代わりに JSON-RPC エラーコード `-32602` (無効なパラメータ) `ResourceNotFoundException`を返します`-32004`。これは、存在しないリソースに対して MCP 2026-07-28 仕様が使用するコードと一致します。

エラー応答のサンプル:

```json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32005,
    "message": "Session operation in progress, please retry"
  }
}
```

### MCP サーバーからのレスポンス
<a name="mcp-error-handling-server-status"></a>

MCP サーバーが次のいずれかのステータスコードを返すと、サービスはそのステータスコードとレスポンス本文をクライアントに返します。その他のステータスコードの場合、サービスは を返します`RuntimeClientError`。
+  **バージョン `2026-07-28`以降**: 200、202、400、401、403、404。その他のステータスコードは HTTP 424 を返します。
+  **バージョン `2025-11-25`以前**: 200 および 202。その他のステータスコードは HTTP 200 を返します。

### RetryableConflictException の再試行
<a name="mcp-error-handling-retryable-conflict"></a>

 `ConflictException` および はエラーコード`RetryableConflictException`を共有`-32005`し、メッセージによって異なります。サービスは、プロビジョニングまたは切断されているセッションをオペレーションがターゲット`RetryableConflictException`にすると を返します。短いエクスポネンシャルバックオフで再試行 — MCP クライアントは自動再試行しません。バージョン `2025-11-25`以前では、レスポンスは HTTP 200 であるため、レスポンス本文を調べて検出します。

## OAuth 認証レスポンス
<a name="mcp-oauth-authentication-responses"></a>

OAuth 設定のエージェントは、[RFC 6749 (OAuth 2.0) ](https://datatracker.ietf.org/doc/html/rfc6749)認証標準に従います。認証がない場合、サービスは WWW-Authenticate ヘッダー ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ごと) を含む 401 Unauthorized レスポンスを返します。これにより、クライアントは GetRuntimeProtectedResourceMetadata API を通じて認可サーバーエンドポイントを検出できます。

### 401 Unauthorized
<a name="mcp-401-unauthorized"></a>

認可ヘッダーが欠落しているか空の場合に返されます。

レスポンスには WWW-Authenticate ヘッダーが含まれます。

```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

**注記**  
SigV4-configuredのエージェントは HTTP 403 を返し、`WWW-Authenticate`ヘッダーは含まれません。