View a markdown version of this page

MCP-Protokollvertrag - Amazon Grundgestein AgentCore
Anforderungen an die Implementierung von ProtokollenAnforderungen an ContainerPfadanforderungenAntworten auf die OAuth-Authentifizierung

MCP-Protokollvertrag

Machen Sie sich mit den Anforderungen für die Implementierung des Model Context Protocol (MCP) vertraut, sodass Agenten Tools und Agentserver aufrufen können.

Beispielcode finden Sie unter Bereitstellen von MCP-Servern in AgentCore Runtime.

Anforderungen an die Implementierung von Protokollen

Ihr MCP-Server muss diese spezifischen Protokollanforderungen implementieren:

  • Transport: Streamable-http Transport ist erforderlich. Verwenden Sie standardmäßig den statusfreien Modus (stateless_http=True), um die Kompatibilität mit AWS der Sitzungsverwaltung und dem Lastenausgleich zu gewährleisten.

  • Sitzungsverwaltung: Die Plattform fügt automatisch einen Mcp-Session-Id Header für die Sitzungsisolierung hinzu. Im statusfreien Modus müssen Server den statusfreien Betrieb unterstützen, damit plattformgenerierte Mcp-Session-Id Header nicht zurückgewiesen werden.

Tipp

Amazon Bedrock unterstützt AgentCore auch stateful-MCP-Server (stateless_http=False), die Funktionen wie Exicitation (Multi-Turn-Benutzerinteraktionen) und Sampling (Inhalt) ermöglichen. LLM-generated Der Stateful-Modus ist erforderlich, wenn Ihr MCP-Server den Sitzungskontext für mehrere Anfragen innerhalb desselben Tool-Aufrufs aufrechterhalten muss. Weitere Informationen und Beispiele finden Sie unter Stateful MCP-Serverfunktionen.

MCP-Sitzungsmanagement und MicroVM-Sperrfähigkeit

Das Model Context Protocol (MCP) verwendet den Mcp-Session-Id Header, um den Sitzungsstatus zu verwalten und Anfragen weiterzuleiten. Die MCP-Spezifikation finden Sie unter MCP Streamable HTTP Transport.

MicroVM Stickiness: Amazon Bedrock AgentCore verwendet den Mcp-Session-Id Header, um Anfragen an dieselbe MicroVM-Instanz weiterzuleiten. Kunden müssen die Mcp-Session-Id zurückgegebenen Daten in der Antwort erfassen und in alle nachfolgenden Anfragen aufnehmen, um die Sitzungsaffinität sicherzustellen. Ohne eine konsistente Sitzungs-ID kann jede Anfrage an eine neue MicroVM weitergeleitet werden, was zu zusätzlicher Latenz aufgrund von Kaltstarts führen kann.

Zustandsloses MCP (): stateless_http=True

  • Die Plattform generiert das Mcp-Session-Id und nimmt es in die Anfrage an Ihren MCP-Server auf.

  • Ihr MCP-Server muss die von der Plattform bereitgestellte Sitzungs-ID akzeptieren (lehnen Sie sie nicht ab).

  • Die Plattform gibt in der Antwort dasselbe Mcp-Session-Id an den Client zurück.

  • Der Client muss diese Sitzungs-ID in allen nachfolgenden Anfragen zur MicroVM-Affinität angeben.

Stateful-MCP (): stateless_http=False

  • Der Client sendet die Initialisierungsanforderung ohne Header. Mcp-Session-Id

  • Die Plattform kehrt Mcp-Session-Id in der Antwort zurück.

  • Der Client muss dies Mcp-Session-Id in allen nachfolgenden Anfragen sowohl für den Sitzungsstatus als auch für die MicroVM-Affinität angeben.

Weitere Informationen zur statusbehafteten MCP-Sitzungsverwaltung finden Sie in der MCP-Sitzungsverwaltungsspezifikation.

Anmerkung

In beiden Modi gibt Amazon Bedrock AgentCore immer einen Mcp-Session-Id Header an Kunden zurück. Erfassen Sie diesen Header immer und verwenden Sie ihn erneut, um eine optimale Leistung zu erzielen.

Anforderungen an Container

Ihr MCP-Server muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:

  • Host: 0.0.0.0

  • Port: 8000 - Standardport für die MCP-Serverkommunikation (unterscheidet sich vom HTTP-Protokoll)

  • Plattform: ARM64-Container — Für die Kompatibilität mit der AWS Amazon AgentCore Bedrock-Laufzeitumgebung erforderlich

Pfadanforderungen

/mcp — POST

Zweck

Empfängt MCP-RPC-Nachrichten und verarbeitet sie mithilfe der Toolfunktionen Ihres Agenten. Vollständige Weitergabe der InvokeAgentRuntimeAPI-Payload mit standardmäßigen MCP-RPC-Nachrichten

Format der Antwort

JSON-RPC basiertes request/response Format, das application/json sowohl als auch als text/event-stream Inhaltstypen für Antworten unterstützt

Anwendungsfälle

Der /mcp Endpunkt dient mehreren wichtigen Zwecken:

  • Aufruf und Verwaltung von Tools

  • Erkennung der Fähigkeiten von Agenten

  • Zugriff auf und Manipulation von Ressourcen

  • Multi-step Workflows für Agenten

Antworten auf die OAuth-Authentifizierung

OAuth-configured Agenten folgen den Authentifizierungsstandards RFC 6749 (OAuth 2.0). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß RFC 7235) zurück, sodass Clients die Endpunkte des Autorisierungsservers über die API ermitteln können. GetRuntimeProtectedResourceMetadata

401 Nicht autorisiert

Wird zurückgegeben, wenn der Authorization-Header fehlt oder leer ist.

Die Antwort enthält den WWW-Authenticate Header:

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

SigV4-configured Agenten geben HTTP 403 mit einem ACCESS_DENIED Fehler zurück und schließen keine WWW-Authenticate Header ein.