MCP Goes Stateless July 28: Four Breaking Changes and How to Migrate Before the Final Spec

TL;DR: MCP's July 28 final spec goes stateless — remove Mcp-Session-Id sessions, add Mcp-Method and Mcp-Name headers to every request, update one error code, and add caching metadata to list responses.

The 2026-07-28 RC was locked May 21 — the 10-week window before the final spec is when Tier 1 SDKs are shipping updated implementations. If you maintain a custom MCP server or transport layer, here are the four changes that break existing code.

1. Remove session management

The initialize/initialized handshake and Mcp-Session-Id header are gone. Client metadata now travels in _meta on every request:

// Old
const session = sessions.get(req.headers['mcp-session-id'])

// New — read from request body
const meta = body.params?._meta ?? {}
const clientCaps = meta.capabilities ?? {}

Infrastructure side: remove sticky-session routing and any Redis store that existed only for MCP sessions.

2. Add two required headers

Streamable HTTP requests must include Mcp-Method and Mcp-Name. Servers reject requests where headers disagree with the body:

await fetch(serverUrl, {
  headers: {
    'Mcp-Method': 'tools/call',
    'Mcp-Name': toolName,
    'MCP-Protocol-Version': '2026-07-28',
  },
  body: JSON.stringify({ method: 'tools/call', params: { name: toolName } })
})

3. Error code -32002 → -32602

Resource-not-found errors move to standard JSON-RPC Invalid Params. Update any client code that matches on the literal code:

// Old
if (err.code === -32002) { /* missing resource */ }

// New — check err.data to distinguish from other -32602 causes
if (err.code === -32602) { /* invalid params or missing resource */ }

4. Caching metadata on list responses

tools/list and resources/list now carry ttlMs and cacheScope:

return res.json({ result: { tools, ttlMs: 300_000, cacheScope: 'global' } })

Clients must respect these fields — replace any ad-hoc TTL conventions you currently use.

Three features in gradual deprecation (12+ month removal window, not breaking July 28): Roots, Logging (migrate to stderr or OpenTelemetry), and Sampling (replace with direct LLM provider calls). Sampling is the most disruptive — if you rely on it for lightweight inference flows, plan that migration now rather than at removal.

On official SDKs: the migration is largely at the SDK layer — update to the version that ships 2026-07-28 support, move session initialization out of app startup, add the new headers. The TypeScript above targets custom transports and low-level clients.

Sources: MCP 2026-07-28 RC announcement, byteiota: MCP goes stateless, DEV.to: every breaking change and how to migrate, tokenmix.ai: full MCP protocol changelog 2026