Einen HTTP-MCP-Server auf 2026-07-28 migrieren und ältere Clients weiter unterstützen

Ziel

Stand: 25. Oktober 2026. Einen HTTP-MCP-Server auf die Revision 2026-07-28 migrieren und dabei einen ausdrücklich unterstützten Zugangsweg für Clients mit 2025-11-25 erhalten. Vor dem Deployment die versionierten Transportvorgaben, die Nachrichtenschemata und die dokumentierte Unterstützung durch das gewählte SDK erneut prüfen. Dies ist ein Vorschlag für ein Abnahmeverfahren, kein Bericht über eine getestete Migration.

Voraussetzungen

Die Protokollrevisionen der Clients, Initialisierungshandler, Sitzungsspeicher, Callbacks, Abonnements und Autorisierungsrichtlinien erfassen. Einen Staging-Endpunkt hinter einem Gateway mit produktionsnaher Konfiguration, eine Rollback-Konfiguration und Clients für beide Revisionen vorbereiten. Unbedenkliche Testwerkzeuge und separate Testidentitäten verwenden. Die tatsächliche Paketversion des SDK festhalten; eine Protokollrevision ist keine Paketversion.

Schritte

1. Protokollvarianten trennen. Die Kompatibilitätsregeln erlauben beide Verhaltensweisen an einem Endpunkt. Ein bisheriges initialize wählt die bisherige Semantik; moderne Metadaten pro Anfrage wählen die zustandslose Verarbeitung. Das ausgehandelte Verhalten der älteren Revision beibehalten, solange deren Clients unterstützt werden. Moderne Header-Anforderungen nicht pauschal auf die bisherige Initialisierung anwenden.

2. Anfragen in sich vollständig machen. io.modelcontextprotocol/protocolVersion und io.modelcontextprotocol/clientCapabilities in params._meta verlangen. Die Clientidentität wie empfohlen aufnehmen, diese Selbstauskunft jedoch nie zur Autorisierung verwenden. Fähigkeiten oder Anwendungskontext nicht mehr aus der vorherigen Verbindung ableiten. Explizite Kennungen für Zustände bereitstellen, die über mehrere Aufrufe hinweg bestehen.

3. Discovery und Transportvalidierung implementieren. server/discover implementieren, die Version auch in MCP-Protocol-Version angeben und die erforderlichen Header mit dem Body abgleichen. Ein einfacher Discovery-Funktionstest für einen Staging-Endpunkt ohne Authentifizierung lautet:

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Die Beispiel-URL ersetzen. Für geschützte Endpunkte den für das Deployment freigegebenen authentifizierten Testclient verwenden; die Authentifizierung für diesen Test nicht deaktivieren.

4. Ergebnisse und Interaktionen aktualisieren. Für gewöhnliche Ergebnisse resultType: "complete" ausgeben. MRTR für zulässige interaktive Vorgänge implementieren: input_required zurückgeben und anschliessend passende inputResponses sowie den unveränderten opaken requestState mit einer neuen Anfrage-ID entgegennehmen. Die Integrität des Zustands prüfen, wenn er Berechtigungen oder Geschäftslogik beeinflusst; ihn wie empfohlen an die handelnde Identität, die Ablaufzeit und den ursprünglichen Vorgang binden. Wo erforderlich, die einmalige Verwendung serverseitig durchsetzen.

5. Benachrichtigungen und Caching migrieren. Den eigenständigen GET-Benachrichtigungsstream durch subscriptions/listen ersetzen. Anfragegebundenes SSE dort beibehalten, wo es genutzt wird, aber die Wiederaufnahme mit Last-Event-ID entfernen: Das Schliessen eines Antwortstreams signalisiert den Abbruch. Vollständige Ergebnisse, die unter die Caching-Spezifikation fallen, um einen nicht negativen Wert für ttlMs und den passenden cacheScope ergänzen. Zwischenergebnisse und Ergebnisse für MRTR-Wiederholungsanfragen vom Caching ausschliessen.

6. Die Behandlung nicht unterstützter Versionen gezielt testen. Bei einer nicht unterstützten modernen Version wird UnsupportedProtocolVersionError mit den unterstützten Versionen zurückgegeben. Clients sollten es mit einer kompatiblen Version erneut versuchen. Bei HTTP 400 den JSON-RPC-Body prüfen: Erkannte moderne Fehler erfordern eine Korrektur oder die Auswahl einer Version; ein leerer oder nicht erkannter Body erlaubt den Rückgriff auf die bisherige Initialisierung. Nicht allein deshalb auf eine ältere Version zurückfallen, weil eine gültige moderne Anfrage abgelehnt wurde.

7. Das Zusammenspiel mit der Deployment-Umgebung prüfen. In Staging Discovery, den Abruf einer Liste, einen unbedenklichen Aufruf, eine interaktive Wiederholungsanfrage und ein Abonnement über das Gateway ausführen. Dies mit einem älteren Client wiederholen und moderne Anfragen auf verschiedene Instanzen verteilen. Eine unbedenkliche SSE-Antwort unterbrechen und den Abbruch sowie die sichere Fortsetzung des Betriebs ohne Wiederaufnahme des Streams prüfen. Die Autorisierung für jede Identität prüfen und bestätigen, dass die Anfragemetadaten unverändert beim Server ankommen.

Erwartetes Ergebnis

Beide unterstützten Revisionen führen ihre jeweiligen Abläufe vollständig aus. Moderne Vorgänge benötigen keine Transportsitzung; ältere Clients behalten ihren ausgehandelten Lebenszyklus. Die alte Konfiguration verfügbar halten, bis die Abnahmeprüfungen bestanden sind.

Grenzen und Prüfbasis

Die zitierte Spezifikation definiert das Protokollverhalten; die obigen Schritte sind ein Vorschlag für einen Prüfplan aus Betreibersicht. Sie belegen weder SDK-Kompatibilität noch die Sicherheit von Wiederholungen bei geschäftlichen Aktionen oder den erfolgreichen Betrieb mit einem bestimmten Load Balancer. Dafür sind Tests erforderlich, die auf das jeweilige Deployment zugeschnitten sind.