Claude Academy
Wird geladen

StreamableHTTP im Detail

Lektion 102 Min.

StreamableHTTP ist MCPs Lösung für ein grundlegendes Problem: Manche MCP-Funktionalität erfordert, dass der Server Anfragen an den Client stellt, aber HTTP macht dies schwierig. Lass uns erkunden, wie StreamableHTTP diese Einschränkung umgeht und wann du diesen Workaround möglicherweise durchbrechen musst.

Das Kernproblem

Manche MCP-Funktionen wie Sampling, Benachrichtigungen und Logging beruhen darauf, dass der Server Anfragen an den Client initiiert. HTTP ist jedoch dafür ausgelegt, dass Clients Anfragen an Server stellen, nicht umgekehrt. StreamableHTTP löst dies mit einem cleveren Workaround unter Verwendung von Server-Sent Events (SSE).

Wie StreamableHTTP funktioniert

Die Magie geschieht durch einen mehrstufigen Prozess, der persistente Verbindungen zwischen Client und Server herstellt.

Die drei unten aufgeführten Initialisierungsnachrichten; die Initialized Notification trägt die Session-ID und erhält kein Ergebnis zurück.

Einrichtung der anfänglichen Verbindung

Der Prozess beginnt wie jede MCP-Verbindung:

  • Der Client sendet eine Initialize Request an den Server
  • Der Server antwortet mit einem Initialize Result, das einen speziellen mcp-session-id-Header enthält
  • Der Client sendet eine Initialized Notification mit der Session-ID

Diese Session-ID ist entscheidend - sie identifiziert den Client eindeutig und muss in allen zukünftigen Anfragen enthalten sein.

Der SSE-Workaround

Nach der Initialisierung kann der Client eine GET-Anfrage stellen, um eine Server-Sent-Events-Verbindung herzustellen. Dies erzeugt eine langlebige HTTP-Antwort, die der Server nutzen kann, um jederzeit Nachrichten an den Client zu streamen.

GET mcp-server.com/mcp/ mit einem mcp-session-id-Header, beantwortet durch eine SSE-Antwort, die beliebig lange offen gehalten werden kann.

Diese SSE-Verbindung ist der Schlüssel, um Server-zu-Client-Kommunikation zu ermöglichen. Der Server kann nun Anfragen, Benachrichtigungen und andere Nachrichten über diesen persistenten Kanal senden.

Tool-Aufrufe und doppelte SSE-Verbindungen

Wenn der Client einen Tool-Aufruf tätigt, wird es komplexer. Das System erstellt zwei separate SSE-Verbindungen:

Zwischen zwei SSE-Antworten vom MCP-Server sendet der Client eine Call Tool Request POST mit einem mcp-session-id-Header.

  • Primäre SSE-Verbindung: Wird für vom Server initiierte Anfragen verwendet und bleibt unbegrenzt offen
  • Tool-spezifische SSE-Verbindung: Wird für jeden Tool-Aufruf erstellt und schließt sich automatisch, sobald das Tool-Ergebnis gesendet wurde

Nachrichten-Routing

Verschiedene Arten von Nachrichten werden über unterschiedliche Verbindungen geleitet:

  • Fortschrittsbenachrichtigungen: Werden über die primäre SSE-Verbindung gesendet
  • Logging-Nachrichten und Tool-Ergebnisse: Werden über die tool-spezifische SSE-Verbindung gesendet

Call Tool Request POSTs an mcp-server.com/mcp/ mit dem mcp-session-id-Header; SSE-Antworten können beliebig lange offen bleiben.

Konfigurations-Flags, die den Workaround durchbrechen

StreamableHTTP enthält zwei wichtige Konfigurationsoptionen:

  • stateless_http
  • json_response

Das Setzen dieser Optionen auf True kann den SSE-Workaround-Mechanismus durchbrechen. Du möchtest diese Flags vielleicht in bestimmten Szenarien aktivieren, aber dies schränkt die vollständige MCP-Funktionalität ein, die von der Server-zu-Client-Kommunikation abhängt.

Wichtige Erkenntnisse

StreamableHTTP ist komplexer als andere MCP-Transporte, weil es die Einschränkungen von HTTP umgehen muss. Der SSE-basierte Workaround ermöglicht vollständige MCP-Funktionalität über HTTP, aber das Verständnis des Dual-Connection-Modells ist entscheidend für Debugging und Optimierung.

Wenn du MCP-Anwendungen mit StreamableHTTP erstellst, denke daran, dass Session-IDs für alle Anfragen nach der Initialisierung erforderlich sind und dass das System automatisch mehrere SSE-Verbindungen verwaltet, um verschiedene Arten der Server-zu-Client-Kommunikation zu handhaben.