Vorteile der Verwendung von Sitzungen Aktivieren Sie Sitzungen auf Ihrem Gateway Lebenszyklus der Sitzung Benutzeridentität und Umfang der Sitzung Timeout und Ablauf der Sitzung Fehlerbehandlung Codebeispiele

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, für die eine Statusverfolgung über mehrere Anfragen hinweg erforderlich ist.
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:

Der Client sendet eine initialize Anfrage an das Gateway.
Das Gateway erstellt eine Sitzung, speichert Sitzungsmetadaten und gibt Mcp-Session-Id im Antwort-Header ein eindeutiges Ergebnis zurück.
Der Client nimmt den Mcp-Session-Id Header in alle nachfolgenden Anfragen auf.
Das Gateway überprüft bei jeder Anfrage die Existenz, den Ablauf und die Benutzeridentität (für authentifizierte Gateways) der Sitzung.
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 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

Beispiel

curl

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"
    }
  }
}

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"
      }
    }
}'

Python requests package


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))

MCP Client


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"
))

Strands MCP Client


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)

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Fortschrittliche Themen

Antwort-Streaming