What the 2026-07-28 MCP release broke, and how to migrate | Portkeel
The MCP specification revision 2026-07-28, published 28 July 2026, is the largest change since the protocol launched. It removes protocol-level sessions and the initialization handshake, reclassifies the HTTP+SSE transport as deprecated, and deprecates Roots, Sampling and Logging under a new twelve-month policy. Any server built against 2025-11-25 or earlier now negotiates a superseded revision. The migration below is ordered the way the work actually has to happen, not the way the changelog lists it.
What actually changed
Four things matter for a running server. Sessions are gone at the protocol level, and the Mcp-Session-Id header with them. The initialization handshake is removed; the protocol version and capabilities now travel in request metadata. The older HTTP+SSE transport is reclassified as deprecated in favour of Streamable HTTP. And Roots, Sampling and Logging are deprecated under a twelve-month minimum removal window.
The lead maintainer’s own framing was that “a lot of things that made MCP are gone”, and that teams who rolled their own implementation face real uplift. That is the honest read. It is also why maintenance stopped being a sales claim on 28 July and became a demonstrable fact.
Sessions and the handshake
If your server held per-session state keyed on Mcp-Session-Id, that state now has nowhere to live. It has to move to explicit handles carried in each request, or to your own storage keyed on the request’s identity.
// before (2025-11-25): state keyed on the session
sessions[req.headers['mcp-session-id']].cart
// after (2026-07-28): explicit handle in the request
store.get(req.params.cart_handle)Transport: HTTP+SSE is deprecated
Serve Streamable HTTP. Keep any historical /sse path as an alias so old clients do not hard-fail, but do not treat it as a distinct supported transport, because it is on the clock now.
Roots, Sampling and Logging
These three are deprecated, not removed. That distinction is the whole planning problem, and the next post in this cluster is about it. For now: inventory where you use them, because “it still works” is the wrong test when a twelve-month window is running.
The migration checklist
| Step | What to do |
|---|---|
| 1 | Identify the revision your server negotiates |
| 2 | Move per-session state to explicit handles |
| 3 | Replace the handshake with request-metadata discovery |
| 4 | Serve Streamable HTTP; alias any /sse path |
| 5 | Inventory Roots, Sampling and Logging usage |
| 6 | Re-run the acceptance script against every client |
How to verify
Compatibility is not symmetric. A server on the new revision may not work with an old client, and the reverse also holds, so “it connected once” proves nothing. Run your acceptance script against every client you support, or check the negotiated revision directly. The 60-second spec version check walks through three ways to read it.
What we did to our own server
We migrated the reference build the week the revision shipped. The real diff, the wire captures, and the elapsed time belong here rather than a summary of them.
If you already built a server and are not sure where it stands, that is exactly what the audit and migration service is for, and what the deprecation-window post explains in planning terms.