# AgentCore ゲートウェイで MCP セッションを使用する
MCP セッションは、クライアントと AgentCore ゲートウェイ間のステートフルインタラクションを有効にします。セッションを有効にすると、ゲートウェイは初期化中に一意のセッション識別子を生成し、複数のリクエストにわたって状態を維持し、誘発やサンプリングなどの高度な MCP 機能を有効にします。
## セッションを使用する利点
**ステートフル MCP サーバーターゲットインタラクション**
ゲートウェイは MCP サーバーターゲットのセッション ID を保存し、その後のツール呼び出しで再利用します。これにより、すべてのリクエストの再初期化が回避され、ターゲットは呼び出し間でコンテキストを維持できます。
**AgentCore ランタイムターゲットによる応答の高速化**
ターゲットのセッションが再利用されると、AgentCore ランタイムはリクエストごとに新しい MCP サーバー接続をコールドスタートする必要がないため、応答時間が短縮されます。
**高度な MCP 機能を有効にする**
セッションは[、複数のリクエストで状態を追跡する必要がある誘発](gateway-mcp-elicitation.md)と[サンプリング](gateway-mcp-sampling.md)の前提条件です。
**ユーザースコープのセキュリティ (認証されたゲートウェイ)**
インバウンド認証を使用するゲートウェイの場合、セッションは検証済みユーザー ID にバインドされ、セッションのハイジャックが防止されます。
## ゲートウェイでセッションを有効にする
セッションを有効にするには、ゲートウェイを作成または更新するときに `sessionConfiguration` `protocolConfiguration.mcp`フィールドに を指定します。
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
}
}
}
}
```
`sessionTimeoutInSeconds` パラメータはオプションです。省略した場合、デフォルトのタイムアウトは 3600 秒 (1 時間) です。有効な範囲は 900 (15 分) から 28800 (8 時間) です。タイムアウトは、最初の`initialize`リクエストから計算された絶対値です。
誘発やサンプリングなどのセッションに依存する機能も有効にするには、レスポンスストリーミングをさらに有効にする必要があります。
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
},
"streamingConfiguration": {
"enableResponseStreaming": true
}
}
}
}
```
**注記**
ゲートウェイでセッションが有効になっている場合、ゲートウェイターゲット`metadataConfiguration`のヘッダー伝達設定の `Mcp-Session-Id`に を含めることはできません。ゲートウェイはセッション IDs。そうしようとすると、HTTP 400 Bad Request エラーが返されます。
## セッションライフサイクル
セッションライフサイクルは、MCP プロトコルの初期化フローに従います。
1. クライアントはゲートウェイに`initialize`リクエストを送信します。
1. ゲートウェイはセッションを作成し、セッションメタデータを保存し、レスポンスヘッダー`Mcp-Session-Id`に一意の を返します。
1. クライアントは、後続のすべてのリクエストに `Mcp-Session-Id`ヘッダーを含めます。
1. ゲートウェイは、各リクエストでセッションの存在、有効期限、およびユーザー ID (認証されたゲートウェイの場合) を検証します。
1. セッションがタイムアウトするか、クライアントが切断されると、セッションは期限切れになります。
セッション内の MCP サーバーターゲットへの最初のツール呼び出しで、ゲートウェイはターゲットとの接続を初期化し、ターゲットのセッション ID を保存します。同じターゲットへの後続のツール呼び出しでは、この保存されたセッション ID が再利用されるため、反復的な初期化を回避できます。
## ユーザー ID とセッションのスコープ
セッションは、セッションのハイジャックを防ぐために、認証されたユーザー ID に限定されます。ゲートウェイは、ゲートウェイで設定されたインバウンド認証方法に応じてユーザー ID を異なる方法で取得します。
| 認証方法 | ユーザー識別子 | 動作 |
| --- | --- | --- |
| OAuth / OIDC | `sub` JWT トークンからの クレーム | フルスコープ。セッションを作成したユーザーのみがセッションを使用できます。`sub` クレームは OIDC 仕様で必須であり、発行者内でローカルに一意であり、大文字と小文字が区別され、再割り当てされることはありません。 |
| AWS IAM (SigV4) | [プリンシパル ARN] | フルスコープ。セッションを作成した IAM プリンシパルのみが使用できます。プリンシパル ARN はグローバルに一意であり AWS、IAM エンティティの存続期間中は変更できません。例: `arn:aws:iam::123456789012:user/john-doe` |
| 認証なし | なし | **ユーザースコープはありません。**セッションは使用できますが、どの ID にもバインドされません。セッション ID を持つユーザーは誰でもセッションとやり取りできます。 |
**重要**
インバウンド認証のないゲートウェイの場合、セッションには [MCP 仕様のセキュリティ上の考慮事項](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#security-considerations)で説明されているように、**セッションハイジャックのリスク**があります。セッション ID がリークまたは推測された場合、別の当事者がセッションを再開できます。非認証セッションは、機密データを処理する本番ワークロードではなく、開発とテストにのみ使用します。
認証されたゲートウェイの場合、別のユーザーが既存のセッション ID を使用しようとすると、ゲートウェイは HTTP 404 Not Found を返します。セッションは他のユーザーには表示されません。
## セッションのタイムアウトと有効期限
セッションタイムアウトは、最初の`initialize`リクエストから計算されます。タイムアウト期間が過ぎると、セッションは期限切れになり、使用できません。
+ **デフォルトのタイムアウト**: 3600 秒 (1 時間)
+ **設定可能な範囲**: 900 秒 (15 分) ～ 28800 秒 (8 時間)
ゲートウェイセッションがタイムアウトする前に MCP サーバーターゲットのセッションが期限切れになると、ゲートウェイはターゲットで透過的に再初期化し、保存されたターゲットセッション ID を更新します。ゲートウェイセッションはアクティブのままです。
## エラー処理
| シナリオ | HTTP ステータス | 説明 |
| --- | --- | --- |
| セッション対応ゲートウェイに`Mcp-Session-Id`ヘッダーがない | 400 Bad Request | 以降のすべてのリクエストには、セッションヘッダーが含まれている`initialize`必要があります。 |
| 無効または期限切れのセッション ID | 404 Not Found | セッションが存在しないか、タイムアウトしました。 |
| 異なるユーザーが別のユーザーのセッション (認証されたゲートウェイ) を使用しようとする | 404 Not Found | セッションは他のユーザーには表示されません。 |
| `Mcp-Session-Id` セッションが有効になってい`metadataConfiguration`る場合のターゲット内の | 400 Bad Request | ターゲットを作成または更新するときにコントロールプレーンに返されます。 |
## コードサンプル
**Example**
1. セッションを開始する`initialize`リクエストを送信します。
```
curl -X POST \
https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": "init-request",
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}'
```
レスポンスには `Mcp-Session-Id`ヘッダーが含まれます。
```
HTTP/1.1 200 OK
Mcp-Session-Id: session-abc123def456
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "init-request",
"result": {
"protocolVersion": "2025-06-18",
"capabilities": {
"tools": { "listChanged": true }
},
"serverInfo": {
"name": "agentcore-gateway",
"version": "1.0.0"
}
}
}
```
1. 後続のリクエストにセッション ID を含めます。
```
curl -X POST \
https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Mcp-Session-Id: session-abc123def456" \
-d '{
"jsonrpc": "2.0",
"id": "call-tool-request",
"method": "tools/call",
"params": {
"name": "searchProducts",
"arguments": {
"query": "wireless headphones"
}
}
}'
```
1.
```
import requests
import json
gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp"
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
# Step 1: Initialize and get session ID
init_response = requests.post(gateway_url, headers=headers, json={
"jsonrpc": "2.0",
"id": "init-request",
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "my-agent", "version": "1.0.0"}
}
})
session_id = init_response.headers["Mcp-Session-Id"]
print(f"Session ID: {session_id}")
# Step 2: Use session ID in subsequent requests
headers["Mcp-Session-Id"] = session_id
tool_response = requests.post(gateway_url, headers=headers, json={
"jsonrpc": "2.0",
"id": "call-tool-request",
"method": "tools/call",
"params": {
"name": "searchProducts",
"arguments": {"query": "wireless headphones"}
}
})
print(json.dumps(tool_response.json(), indent=2))
```
1.
```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio
async def use_session(url, token):
headers = {"Authorization": f"Bearer {token}"}
async with streamablehttp_client(url=url, headers=headers) as (
read_stream, write_stream, _
):
async with ClientSession(read_stream, write_stream) as session:
# Initialize - session ID is managed automatically by the MCP client
init_response = await session.initialize()
print(f"Initialized: {init_response}")
# Subsequent calls reuse the session automatically
tool_response = await session.call_tool(
name="searchProducts",
arguments={"query": "wireless headphones"}
)
print(f"Tool response: {tool_response}")
return tool_response
asyncio.run(use_session(
url="https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
token="YOUR_ACCESS_TOKEN"
))
```
1.
```
from mcp.client.streamable_http import streamablehttp_client
from strands import Agent
from strands.tools.mcp import MCPClient
mcp_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp"
access_token = "YOUR_ACCESS_TOKEN"
mcp_client = MCPClient(
lambda: streamablehttp_client(
mcp_url, headers={"Authorization": f"Bearer {access_token}"}
)
)
# Strands MCP client handles session management automatically
with mcp_client:
agent = Agent(tools=mcp_client.list_tools_sync())
response = agent("Search for wireless headphones")
print(response)
```