Migration eines MCP-Servers auf die Spezifikation 2026-07-28: Zwanzig Minuten, Schritt für Schritt

Nichts ist kaputtgegangen – und das ist das Beunruhigende. Am 28. Juli 2026 veröffentlichte das Model Context Protocol seine Spezifikation 2026-07-28, den größten Wandel seit dem ersten Erscheinen von Remote MCP. Ein Header, auf den Server angewiesen waren, wurde zurückgezogen und das Transportmodell änderte seine Struktur, doch die Kompatibilität blieb gewahrt. Die Server funktionierten weiterhin ohne Stack-Trace, Warnungen oder Fehlermeldungen.

Das ist die Art von stiller technischer Verschuldung. Sie bleibt verborgen, bis jemand Skalierung benötigt oder bis die zwölfmonatige Deprecations-Frist abläuft und eine Abhängigkeit nicht mehr gewartet wird. Ein Server, der noch die Version 2025-11-25 verwendet, hinkt hinterher. Ein Server, der das veraltete HTTP+SSE-Transportprotokoll nutzt, verwendet aktuell etwas, das bereits veraltet ist, zusammen mit möglicherweise drei Funktionen, deren Unterstützung bald endet.

Im Folgenden wird erläutert, was sich geändert hat, warum die Betreuer dies getan haben und wie man auf dem Laufenden bleibt. Für die meisten Server sind etwa zwanzig Minuten Arbeit nötig. Eine Änderung jedoch ist bei einigen Servern eine echte Neuschreibung, und das sollte man gleich zu Beginn klarstellen.

Warum die Sessions wegfielen

Der ingenieurtechnische Antrieb erklärt alles Weitere. MCP wurde Ende 2024 als sessionsbasiertes Protokoll eingeführt: Der Client startet mit einem initialize-Handshake, der Server gibt eine Mcp-Session-Id aus, und jede nachfolgende Anfrage enthält diese ID. Das passte zum ursprünglichen Szenario mit einem Client und einem Server auf einem Rechner über stdio.

Dann wechselten die Server auf echte Infrastrukturen, und das Design stieß an seine Grenzen. Googles Ingenieure beschrieben dies in ihrer Dokumentation zur stateless Update-Methode: Ein Design, das für einen einzelnen lokalen Client ideal war, funktionierte nicht mehr, sobald MCP-Server über cloud-basierte Infrastrukturen verteilt wurden.

Betrachten Sie, was eine Session-ID erfordert: Entweder sticky Routing, damit ein Client stets auf dieselbe Instanz zugreifen kann, oder ein gemeinsamer Session-Speicher, den jede Instanz abfragen kann. Ein einfacher HTTP-Service benötigt plötzlich load balancing, das Affinitäten berücksichtigt, sowie etwas wie Redis – lediglich um die Übertragung zu gewährleisten –, bevor er irgendetwas Nützliches leisten kann.

Der Veröffentlichungspost von David Soria Parra und Den Delimarsky formuliert es unverblümt: MCP wechselt von einem bidirektionalen, zustandsbehafteten Protokoll zu einem zustandslosen Request/Response-Protokoll, was zu den am häufigsten geforderten Änderungen seitens Entwickler war, die Zuverlässigkeit und Skalierbarkeit wünschten. Die Dringlichkeit spiegelt das Ausmaß wider: Die Tier-1-SDKs verzeichnen fast eine halbe Milliarde Downloads pro Monat, und die TypeScript- sowie Python-SDKs haben jeweils bereits eine Milliarde Downloads erreicht. Ein Protokoll in diesem Umfang kann es sich nicht leisten, bei jeder Bereitstellung immer wieder das Problem der Session-Affinität lösen zu müssen.

Die Sitzung ist somit vorbei. Jeder Anfrage liegt ihre eigene Protokollversion, Klientenidentität und -fähigkeiten bei, was bedeutet, dass jede Anfrage jede Instanz hinter einem einfachen Round-Robin-Balancer ohne gemeinsame Speicherung erreichen kann. Alles Weitere folgt daraus.

Fünf Änderungen, die man verstehen muss

1. Kein Handshake, kein Sitzungshintergrund

Der Austausch von initialize und initialized sowie der Mcp-Session-Id-Header wurden offiziell abgeschafft (SEP-2575 und SEP-2567). Jede Anfrage steht für sich, wobei Version, Klientenidentität und -fähigkeiten in _meta enthalten sind. Eine Anfrage nach der neuen Spezifikation sieht so aus:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"},
 "_meta":{"io.modelcontextprotocol/clientInfo":
              {"name":"my-app",
                "version":"1.0"}
          }}}

Ein Kunde, der im Voraus die Fähigkeiten eines Servers erfahren möchte, kann den neuen server/discover RPC verwenden, der optional ist und nicht mehr als obligatorische Verbindungsprüfung dient.

Eine häufige Befürchtung ist, dass Anwendungen dann keinen Zustand mehr speichern können. Das ist jedoch weiterhin möglich. Das Entfernen der Sitzung aus dem Protokoll zwingt eine Anwendung nicht dazu, zustandslos zu sein. Wenn ein Server Kontinuität benötigt, sollte ein Tool einen expliziten Handle erstellen, den das Modell später als Argument zurückgibt. Das funktioniert besser als der Zustand, der im Transportmechanismus versteckt wird, da das Modell den Handle sehen und ihn von Tool zu Tool weitergeben kann. Sichtbarer Zustand ist besser als unsichtbarer Zustand.

2. Zwei obligatorische Header

Von nun an müssen Streamable-HTTP-Anfragen Mcp-Method und Mcp-Name enthalten (SEP-2243), und der Server soll bestätigen, dass sie mit der Anfrage übereinstimmen. Vorteile für die Infrastruktur: Ein Gateway, ein Rate-Limiter oder eine WAF können mithilfe der Header leiten und messen sowie das JSON-Parsern ausweichen. Jeder, der aufgrund der Versteckung des Tool-Namens innerhalb des Payloads die toolbezogene Rate-Limitierung am Edge aufgegeben hat, hat nun eine Lösung.

3. Cachebare Listeantworten

Die Ergebnisse von tools/list, prompts/list, resources/list und resources/read enthalten nun ttlMs sowie cacheScope (SEP-2549) und werden in einer deterministischen Reihenfolge zurückgegeben. Clients können Ihren Tool-Katalog cachen und so die Caches der upstream-Prompts bei erneuten Verbindungen stabil halten. Da ein großer Teil der Token-Kosten eines Agents durch wiederholt gesendete Tool-Definitionen entsteht, dient dies zugleich als Kostensenkungsfunktion.

4. Striktere Autorisierung

Vier Änderungen wurden eingeführt, wovon eine möglicherweise einen bereits bekannten Fehler erklärt:

• Authentifizierungsserver sollten den in RFC 9207 definierten iss-Parameter zurückgeben, und Clients müssen diesen vor der Einlösung eines Codes überprüfen (SEP-2468), wodurch ein Missbrauchsrisiko beseitigt wird.
• Die Clients legen während der dynamischen Client-Anmeldung application_type fest (SEP-837), wodurch die Autorisierungsserver aufhören, localhost-Umleitungen für Desktop- und CLI-Apps abzulehnen. Wenn der OAuth-Flow einer CLI jemals aufgrund eines redirect_uri-Fehlers fehlgeschlagen ist, liegt das wahrscheinlich daran.
• Die Client-Zertifikate sind mit dem Ersteller verbunden und können nicht auf verschiedenen Autorisierungsservern wiederverwendet werden (SEP-2352).
• Die dynamische Client-Anmeldung selbst ist offiziell veraltet und wird durch Client-ID-Metadokumente ersetzt. Sie funktioniert weiterhin, wird aber in einer späteren Version entfernt.

5. Die Veraltungsliste

Das Wort „veraltet“ hat hier große Bedeutung. Roots, Sampling and Logging (SEP-2577) sind zwar veraltet, aber weiterhin funktionsfähig – es bleibt mindestens ein Jahr Zeit, und neue Implementierungen sollten sie nicht verwenden. Der herkömmliche HTTP+SSE-Transport ist ebenfalls veraltet, wobei ebenfalls ein Jahr Zeit für den Umstieg bleibt.

Tasks wurde umgezogen, nicht deaktiviert. Es wechselte vom experimentellen Kern in die Erweiterung io.modelcontextprotocol/tasks, wird mit tasks/get abgerufen und über die neue Funktion tasks/update aktualisiert (SEP-2663). Benachrichtigungen über Änderungen fließen nun über einen einzigen subscriptions/listen-Stream, für den sich die Clients aktiv anmelden müssen.

Die beste Nachricht hier ist eine formelle Deaktivierungsrichtlinie mit einer Mindestdauer von zwölf Monaten. Real Python fügt hinzu, dass eine Frist von 90 Tagen nur auf aktuelle Sicherheitsrisiken anwendbar ist – das ist mehr Vorlaufzeit, als das Ökosystem je zuvor hatte. Diese Richtlinie könnte wichtiger sein als alles andere in dieser Version, denn sie unterscheidet zwischen einem Protokoll, mit dem man experimentiert, und einem, auf dem man ein Geschäft aufbauen kann.

Die Migration, Schritt für Schritt

Die Anleitung verwendet das Python SDK, dessen Umbenennung die störendste der vier ist, obwohl die Struktur in TypeScript, Go und C# gleich bleibt.

Minuten 0 bis 2: Entscheidung treffen. Wenn der Server Sampling, Elicitation oder Roots verwendet, ist eine vollständige Neuschreibung erforderlich, wie weiter unten erläutert. Wenn er nur Tools und Ressourcen bereitstellt, kann man fortfahren.

Minuten 2 bis 5: SDK aktualisieren. Das Python SDK erreichte am Tag der Veröffentlichung der Spezifikation die Version 2.0.0, und pip install mcp lädt nun die Versionen der 2.x-Reihe herunter.

pip install --upgrade "mcp>=2"

Eine wichtige Änderung, die man kennen sollte: Die SDK-Version wechselte von httpx zu httpx2. Falls httpx an anderer Stelle in Ihrem Abhängigkeitsbaum festgelegt ist, kümmern Sie sich bitte umgehend darum.

Minuten 5 bis 10: Umbenennung der Klasse. Jeder Python-Server wird davon betroffen sein. FastMCP heißt nun MCPServer – es gibt weder Alias noch einen Ersatzmechanismus für die Veraltete Version:

# Before, on mcp 1.x
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

# After, on mcp 2.x
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("Demo")

Drei weitere Umbenennungen kommen in derselben Version dazu:

# Wire types are snake_case now
result.isError        # → result.is_error
tool.inputSchema      # → tool.input_schema

# The error class matches the new capitalisation
except McpError:      # → except MCPError:

mcp-types ist nun ein eigenständiges Paket, doch mcp.types bleibt weiterhin die unterstützte Import-Route, sodass diese Importe weiterhin funktionieren. Eine Warnung: Personen, die das eigenständige fastmcp-Paket anstelle des offiziellen SDKs verwenden, werden nicht betroffen. Es handelt sich dabei um ein anderes Projekt mit eigenen 3.x-Versionen, und ein Grund für die Umbenennung ist es, die beiden voneinander zu trennen.

Minuten 10 bis 15: Entfernen Sie die Session-Strukturen. Session-Wörterbücher, Aufräum-Timer sowie eine nur für den Session-Zustand konstruierte Redis-Instanz können alle gelöscht werden. Falls eine Kontinuität zwischen den Aufrufen wirklich erforderlich ist, verwenden Sie das Handle-Muster:

# Instead of hiding state in a session the model can't see:
@mcp.tool()
def open_dataset(path: str) -> str:
    """Open a dataset and return a handle for subsequent calls."""
    handle = register_dataset(path)     # your own store, your own TTL
    return handle                        # the model now HOLDS this

@mcp.tool()
def query_dataset(handle: str, query: str) -> list[dict]:
    """Query a previously opened dataset."""
    return lookup(handle).query(query)

Minuten 15 bis 18: Überprüfen Sie die neuen Header. Der Server muss prüfen, ob die eingehenden Werte für Mcp-Method und Mcp-Name mit der Anfrage übereinstimmen. Das SDK kümmert sich um den üblichen Ablauf, doch hinter einem benutzerdefinierten Gateway oder einem manuell implementierten Transport muss dies end-to-end überprüft werden.

Minuten 18 bis 20: Beheben Sie den Fehlercode. Es ist leicht, diesen zu übersehen, was zu verwirrendem Verhalten des Clients führt. Fehler wegen fehlender Ressourcen sollten den standardmäßigen JSON-RPC-Code -32602 für ungültige Parameter verwenden und nicht MCPs eigenen Code -32002.

Sicher für die Veröffentlichung

Ein einziger MCPServer dient beiden Protokollgenerationen, sodass ein Client aus der 2025er-Generation weiterhin mit einem migrierten Server funktioniert, ohne dass auf keiner Seite etwas konfiguriert werden muss. Deshalb kann dies an einem gewöhnlichen Dienstag veröffentlicht werden, ohne dass ein spezieller Tag in allen Clients koordiniert werden muss.

Wenn es länger dauert

Server, die Sampling, Elicitation oder ähnliche Methoden verwenden, müssen vollständig umgeschrieben werden – Real Python bezeichnet dies als den wichtigsten Punkt auf der Migrationsliste. Früher konnte der Server eine Anfrage starten und über einen ständig geöffneten zweistufigen Datenfluss eine Rückmeldung an den Client senden. Ein stateless Design verfügt nicht über einen solchen Datenfluss, weshalb stattdessen mehrfache Round-Trip-Anfragen verwendet werden (SEP-2322).

Der neue Ablauf funktioniert wie folgt: Der Server antwortet mit resultType: „input_required“ sowie den Fragen, auf die Antworten benötigt werden. Der Client wiederholt anschließend den ursprünglichen Aufruf und übermittelt seine Antworten in inputResponses. Dadurch ändert sich die Art und Weise, wie Tools programmiert werden. Ein Handler kann nicht mitten im Vorgang pausieren und auf eine Antwort warten. Er kann für eine logische Operation mehrfach aufgerufen werden und muss korrekt weiterarbeiten, sobald die Eingaben eintreffen – daher müssen alle in lokalen Variablen während der Pause gespeicherten Daten an einem Ort abgelegt werden, den ein erneuter Versuch erreichen kann.

Der Nutzen ist real. Der Produktleiter von Supabase sagte, dass eine solche Funktion bereits lange im Entwicklungsplan stand, aber nicht umsetzbar war, da ihr MCP-Server stateless läuft. MRTR macht dies möglich, indem es Tools erlaubt, zunächst mit dem Benutzer zu bestätigen – beispielsweise den Kosten eines neuen Projekts oder einer Abfrage, die Daten löschen würde. Die Entwicklung der Tools wird etwas schwieriger, doch deren stateless-Einsatz in großem Umfang wird dadurch möglich.

Was das neue Protokoll bringt

Manufact betreibt Tausende von MCP-Servern und hält das Open-Source-Framework mcp-use am Laufen. Laut Messungen ist die SDK v2 etwa 83 Prozent kleiner und 25 Prozent schneller – dies wird der neuen Trennung in Client und Server zugeschrieben. In der Übersicht des Ökosystems der Agentic AI Foundation heißt es, dass ein Server nun wie jeder andere HTTP-Service funktioniert und von der von einem Round-Robin-Balancer ausgewählten Instanz antwortet, wobei Gateways über Header den Datenverkehr leiten und Drosselungen vornehmen. Die zwölfmonatige Strategie bedeutet außerdem, dass sich das Protokoll nicht weiter verändert.

Die Übernahme war für einen offenen Standard schnell. Innerhalb weniger Tage haben Infrastrukturanbieter, SDK-Betreuer, Cloud-Plattformen und Tool-Anbieter ihre Unterstützung bekannt gegeben, Migrationshinweise veröffentlicht und Produktimplementierungen herausgegeben. Cloudflare’s Agents SDK handhabte die Spezifikation bereits ab dem ersten Tag, Amazon Bedrock AgentCore stellt den stateless Core bereit, und Microsoft Foundry, Netlify, Figma, Supabase sowie Honeycomb schlossen sich an. Honeycomb gibt an, dass fast ein Fünftel seiner monatlichen interaktiven Abfragen nun von Agents stammt – was erklärt, warum dies wichtig ist. Agents haben die Demo-Phase bereits hinter sich.

Bei 1.x bleiben

Das ist eine legitime Entscheidung. Festlegen und abwarten:

# Buys you time, keeps security patches coming
pip install "mcp>=1.28,<2"

Wissen Sie dort zwei Dinge: Die 1.x-Reihe befindet sich im Wartungsmodus und enthält nur Sicherheitskorrekturen. Zudem ist die Tasks-Erweiterung noch nicht in der Python SDK 2.0-Version enthalten, wodurch Tasks die Kernspezifikation verlassen hat, ohne im SDK zu landen. Für Python-Nutzer, die auf Tasks angewiesen sind, ist Warten die richtige Entscheidung. Legen Sie sich einen Erinnerungstermin im Kalender für den zwölften Monat zu Roots, Sampling und Logging fest, denn Deprecierungszeiträume erscheinen endlos, bis sie tatsächlich enden.

Die Gefahr der stillen Deprecierung

Eine brisante Änderung ist laut: Sie verursacht Build-Fehler, wird bemerkt und anschließend behoben. Eine Deprecierung ist hingegen aus Designgründen leise. Der Server läuft weiter, die Tests bestehen und nichts zeigt Fehler an – während sich die Kosten anhäufen: ein Transport mit Ablaufdatum, keine einfache horizontale Skalierung sowie eine Abhängigkeit im Wartungsmodus, während sich das Ökosystem weiterentwickelt. Die Version in MCP-Protocol-Version ist ein Datum, und es lohnt sich, zu überprüfen, wie alt sie mittlerweile ist.

Für die meisten Server reicht dazu höchstens ein Nachmittag, wobei die eigentliche Arbeit weniger als eine halbe Stunde dauert. Server, die Sampling oder Elicitation verwenden, sollten einen ganzen Tag einplanen und zunächst die MRTR-Spezifikation durchlesen. In jedem Fall sollte dies erledigt werden, bevor die zwölf Monate stillschweigend zu zwei werden.