Every breaking change in the 2026-07-28 MCP spec — and exactly how to migrate — MCP Migration Studio<br>MCP Migration Studio / migration guide · June 9, 2026 · 48 days to the cutover<br>Every breaking change in the 2026-07-28 MCP spec — and exactly how to migrate<br>On July 28, 2026, the Model Context Protocol ships its largest revision since launch. This is not a version bump you can sleep through: the core goes stateless, session IDs disappear from the wire, and the OAuth requirements get materially stricter — seven groups of changes that will break remote servers built against today's spec. Clients that track the protocol, Claude included, will negotiate the new version; servers that don't speak it will degrade quietly and then stop working. Below is every breaking change in the release and the exact migration path for each one — the same checklist we run against the servers we migrate for clients, and against our own.<br>Everything in this guide is based on the official release-candidate announcement on the MCP blog, which lists every change by its SEP number. We cite the SEP for each change so you can verify it against the source instead of taking our word for it.<br>The timeline<br>The release candidate locked on May 21, 2026 . The final spec ships on July 28, 2026 . That is a ten-week validation window, and it exists for one purpose: so SDK maintainers, client vendors, and server operators can migrate against a frozen target instead of chasing a moving one. The changes below are locked — what you migrate to now is what ships.<br>DateMilestone2026-05-21Release candidate locked; the change set is frozenMay 21 → July 28Ten-week validation window for SDKs, clients, and servers2026-07-28Final spec ships; spec-tracking clients negotiate the new versionIf you operate a remote MCP server, the practical reading: you have until late July to get RC-clean without doing anything under pressure, and the clients your users connect from — Claude, Cursor, everything that tracks the spec — will expect the new protocol version once it is final.<br>Stateless core: the handshake and the session ID are gone (SEP-2575, SEP-2567)<br>SEP-2575 removes the initialize / initialized handshake. SEP-2567 removes the Mcp-Session-Id header and protocol-level sessions entirely. Together they make the core of the protocol stateless: no setup phase, and no identifier tying one request to the next.<br>Two mechanisms replace what the handshake used to do. First, protocolVersion, clientInfo, and capabilities now travel in _meta on every request — each request identifies itself instead of leaning on a session established earlier. A post-migration tool call is shaped roughly like this:<br>"jsonrpc": "2.0",<br>"id": 4,<br>"method": "tools/call",<br>"params": {<br>"name": "render_pdf",<br>"arguments": { "document_id": "doc_8f3a" },<br>"_meta": {<br>"protocolVersion": "2026-07-28",<br>"clientInfo": { "name": "example-client", "version": "1.0.0" }<br>}Second, a new server/discover method replaces the upfront capability exchange — clients ask what a server supports when they need to know, rather than caching the answer from an initialize call.<br>What this breaks: anything keyed on the session ID. Auth context, caches, rate limits, an open-document pointer — if it lives under Mcp-Session-Id, it loses its anchor the moment clients stop sending the header. The fix is architectural, not mechanical: every handler becomes self-contained, and application state moves to explicit handles — a tool returns an identifier, and later calls pass it back as an ordinary argument.<br>// Before: state hangs off the protocol session (gone with SEP-2567)<br>sessions[mcpSessionId].document = doc;

// After: the tool mints an explicit handle...<br>return {<br>content: [{ type: "text", text: JSON.stringify({ document_id: "doc_8f3a" }) }],<br>};

// ...and every later call passes it back as a normal argument:<br>// tools/call { name: "append_page",<br>// arguments: { document_id: "doc_8f3a", ... } }If you run on a serverless platform that already builds a fresh server per request — the mcp-handler pattern on Vercel, for instance — you are most of the way there. The audit is for every place your application code reads the session ID.<br>Mandatory Mcp-Method and Mcp-Name headers (SEP-2243)<br>SEP-2243 makes two headers mandatory on streamable HTTP: Mcp-Method and Mcp-Name, mirroring the JSON-RPC method and name from the request body. Servers must reject requests where the headers and the body disagree.<br>The SDK upgrade handles generation and validation. What the SDK cannot handle is your infrastructure: a WAF, reverse proxy, or firewall rule that strips or blocks unknown Mcp-* headers will fail every request, and from the outside it will look like a client bug. Walk the full request path — CDN, WAF, proxy, load balancer — and confirm Mcp-* headers pass through untouched.<br>Multi-round-trip requests replace long-lived SSE (SEP-2260, SEP-2322)<br>Under SEP-2260, a server may only send requests to the client while it is actively processing a client request. The...