# Verwenden Sie MCP-Sitzungen mit Ihrem Gateway AgentCore
MCP-Sitzungen ermöglichen statusbehaftete Interaktionen zwischen Clients und Ihrem Gateway. AgentCore Wenn Sitzungen aktiviert sind, generiert das Gateway bei der Initialisierung eine eindeutige Sitzungs-ID und behält den Status über mehrere Anfragen hinweg bei, wodurch erweiterte MCP-Funktionen wie Auslösung und Sampling aktiviert werden.
## Vorteile der Verwendung von Sitzungen
**Stateful-MCP-Server-Zielinteraktionen**
Das Gateway speichert die Sitzungs-ID des MCP-Serverziels und verwendet sie bei nachfolgenden Toolaufrufen erneut. Dadurch wird eine Neuinitialisierung bei jeder Anfrage vermieden und die Ziele können den Kontext zwischen Aufrufen beibehalten.
**Schnellere Antworten mit Runtime-Zielen AgentCore **
Wenn die Sitzung des Ziels wiederverwendet wird, muss AgentCore Runtime nicht bei jeder Anfrage eine neue MCP-Serververbindung per Kaltstart starten, was zu schnelleren Antwortzeiten führt.
**Aktiviert erweiterte MCP-Funktionen**
[Sitzungen sind eine Voraussetzung für die Erhebung und [Probenahme](gateway-mcp-sampling.md), für die eine Statusverfolgung über mehrere Anfragen hinweg erforderlich ist.](gateway-mcp-elicitation.md)
**User-scoped Sicherheit (authentifizierte Gateways)**
Bei Gateways mit eingehender Authentifizierung sind Sitzungen an die verifizierte Benutzeridentität gebunden, wodurch Sitzungsüberfälle verhindert werden.
## Aktivieren Sie Sitzungen auf Ihrem Gateway
Um Sitzungen zu aktivieren, geben Sie a `sessionConfiguration` in das `protocolConfiguration.mcp` Feld ein, wenn Sie Ihr Gateway erstellen oder aktualisieren.
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
}
}
}
}
```
Der Parameter `sessionTimeoutInSeconds` ist optional. Wenn dieser Wert weggelassen wird, beträgt der Standard-Timeout 3600 Sekunden (1 Stunde). Der gültige Bereich liegt zwischen 900 (15 Minuten) und 28800 (8 Stunden). Das Timeout ist absolut und wird ab der ersten `initialize` Anfrage berechnet.
Um auch Funktionen zu aktivieren, die von Sitzungen abhängen, wie z. B. Erfassung und Sampling, müssen Sie zusätzlich das Antwort-Streaming aktivieren:
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
},
"streamingConfiguration": {
"enableResponseStreaming": true
}
}
}
}
```
**Anmerkung**
Wenn Sitzungen auf einem Gateway aktiviert sind, können Sie die Einstellungen für die Header-Propagierung nicht `Mcp-Session-Id` in die `metadataConfiguration` eines Gateway-Ziels aufnehmen. Das Gateway verwaltet die Sitzungs-IDs intern. Der Versuch, dies zu tun, gibt einen HTTP 400 Bad Request-Fehler zurück.
## Lebenszyklus der Sitzung
Der Sitzungslebenszyklus folgt dem Initialisierungsablauf des MCP-Protokolls:
1. Der Client sendet eine `initialize` Anfrage an das Gateway.
1. Das Gateway erstellt eine Sitzung, speichert Sitzungsmetadaten und gibt `Mcp-Session-Id` im Antwort-Header ein eindeutiges Ergebnis zurück.
1. Der Client nimmt den `Mcp-Session-Id` Header in alle nachfolgenden Anfragen auf.
1. Das Gateway überprüft bei jeder Anfrage die Existenz, den Ablauf und die Benutzeridentität (für authentifizierte Gateways) der Sitzung.
1. Wenn die Sitzung abgelaufen ist oder der Client die Verbindung trennt, läuft die Sitzung ab.
Beim ersten Toolaufruf an ein MCP-Serverziel innerhalb einer Sitzung initialisiert das Gateway eine Verbindung mit dem Ziel und speichert die Sitzungs-ID des Ziels. Bei nachfolgenden Toolaufrufen an dasselbe Ziel wird diese gespeicherte Sitzungs-ID wiederverwendet, wodurch eine wiederholte Initialisierung vermieden wird.
## Benutzeridentität und Umfang der Sitzung
Sitzungen werden auf die authentifizierte Benutzeridentität beschränkt, um Sitzungsmissbrauch zu verhindern. Das Gateway leitet die Benutzeridentität je nach der auf Ihrem Gateway konfigurierten Authentifizierungsmethode für eingehenden Datenverkehr unterschiedlich ab:
| Authentifizierungsmethode | Benutzer-ID | Behavior |
| --- | --- | --- |
| OAuth/OIDC | `sub`Anspruch aus dem JWT-Token | Vollständiger Geltungsbereich. Nur der Benutzer, der die Sitzung erstellt hat, kann sie verwenden. Der `sub` Anspruch ist in der OIDC-Spezifikation vorgeschrieben, ist innerhalb des Emittenten lokal einzigartig, unterscheidet Groß- und Kleinschreibung und wird nie erneut zugewiesen. |
| AWS IAM (SigV4) | Prinzipal-ARN | Vollständiger Geltungsbereich. Nur der IAM-Prinzipal, der die Sitzung erstellt hat, kann sie verwenden. Der Principal-ARN ist weltweit AWS einzigartig und für die gesamte Lebensdauer der IAM-Entität unveränderlich. Beispiel: `arn:aws:iam::123456789012:user/john-doe` |
| Keine Authentifizierung | Keine | **Kein Benutzerbereich.** Sitzungen sind verfügbar, aber nicht an eine Identität gebunden. Jeder mit der Sitzungs-ID kann mit der Sitzung interagieren. |
**Wichtig**
Bei Gateways ohne eingehende Authentifizierung besteht bei Sitzungen das **Risiko, dass eine Sitzung entführt wird, wie in den Sicherheitsüberlegungen** der [MCP-Spezifikation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#security-considerations) beschrieben. Wenn eine Sitzungs-ID durchgesickert ist oder erraten wird, kann eine andere Partei die Sitzung fortsetzen. Verwenden Sie nicht authentifizierte Sitzungen nur für Entwicklungs- und Testzwecke, nicht für Produktionsworkloads, die sensible Daten verarbeiten.
Wenn bei authentifizierten Gateways ein anderer Benutzer versucht, eine bestehende Sitzungs-ID zu verwenden, gibt das Gateway HTTP 404 Not Found zurück — die Sitzung ist für andere Benutzer unsichtbar.
## Timeout und Ablauf der Sitzung
Das Sitzungs-Timeout wird ab der ersten `initialize` Anfrage berechnet. Nach Ablauf des Timeouts läuft die Sitzung ab und kann nicht verwendet werden.
+ **Standard-Timeout**: 3600 Sekunden (1 Stunde)
+ **Konfigurierbarer Bereich**: 900 Sekunden (15 Minuten) bis 28800 Sekunden (8 Stunden)
Wenn die Sitzung eines MCP-Serverziels vor dem Gateway-Sitzungs-Timeout abläuft, wird das Gateway transparent mit dem Ziel neu initialisiert und die gespeicherte Zielsitzungs-ID aktualisiert. Die Gateway-Sitzung bleibt aktiv.
## Fehlerbehandlung
| Szenario | HTTP-Status | Description |
| --- | --- | --- |
| Fehlender `Mcp-Session-Id` Header auf einem sitzungsfähigen Gateway | 400 Bad Request (400 Ungültige Anfrage) | Alle nachfolgenden Anfragen `initialize` müssen den Sitzungsheader enthalten. |
| Ungültige oder abgelaufene Sitzungs-ID | 404 Not Found (404 Nicht gefunden) | Die Sitzung ist nicht vorhanden oder das Timeout ist abgelaufen. |
| Ein anderer Benutzer versucht, die Sitzung eines anderen Benutzers zu verwenden (authentifizierte Gateways) | 404 Not Found (404 Nicht gefunden) | Die Sitzung ist für andere Benutzer unsichtbar. |
| `Mcp-Session-Id`im Ziel`metadataConfiguration`, wenn Sitzungen aktiviert sind | 400 Bad Request (400 Ungültige Anfrage) | Wird beim Erstellen oder Aktualisieren eines Ziels auf der Steuerungsebene zurückgegeben. |
## Codebeispiele
**Example**
1. Senden Sie eine `initialize` Anfrage zum Starten einer Sitzung:
```
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"
}
}
}'
```
Die Antwort enthält den `Mcp-Session-Id` Header:
```
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. Fügen Sie die Sitzungs-ID in nachfolgende Anfragen ein:
```
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)
```