MCP 2026-07-28 Migration Guide: Stateless Requests, Tasks, and Header-Based Routing

The MCP 2026-07-28 specification moves the protocol toward a stateless, routable, cacheable core. The release changes how teams think about sessions, load balancing, server-to-client interactions, catalog caching, authorization hardening, Tasks, and deprecated transport or capability patterns.

What changed at a glance

• The protocol core is stateless and no longer requires the old initialize/initialized exchange or Mcp-Session-Id header.
• Requests carry protocol context and can be routed to any compatible instance behind a normal load balancer.
• Streamable HTTP requests include Mcp-Method and Mcp-Name headers for routing, authorization, and metering.
• List responses can carry cache hints and deterministic ordering.
• Tasks are an extension with polling-oriented task operations.
• Authorization hardening includes issuer validation, credential binding, and movement from Dynamic Client Registration toward Client ID Metadata Documents.
• Legacy HTTP+SSE and several older capabilities have a deprecation window rather than an immediate removal.

1. Audit assumptions about sessions

If your application stores important state in a transport session identifier, make that state explicit. The new stateless core allows requests to land on different instances. Use an application-level handle or durable store when a workflow needs continuity, and pass the handle through the tool interface where appropriate.

2. Update gateways and middleware

Header-based method and tool names give gateways a direct way to route, authorize, meter, and observe requests. Update WAF, rate-limit, policy, and telemetry middleware to preserve and validate those headers. Do not rely only on parsing request bodies after a proxy has already made an access decision.

3. Revisit catalog caching

Tools, prompts, resources, and reads can carry cache hints. A client or gateway can use those hints to reduce repeated discovery traffic. If your catalog changes dynamically, define the freshness behavior and test whether cached descriptions remain consistent with the deployed handlers.

4. Plan for Tasks and long-running work

Long-running workflows need a state model that is visible and recoverable. Treat task creation, progress, polling, failure, cancellation, and completion as explicit events. Track time to first progress, total duration, retries, and terminal outcome rather than treating one long request as the whole workflow.

5. Recheck authorization

The release continues to harden authorization around issuer validation, binding credentials to the issuer that minted them, and moving toward Client ID Metadata Documents. Test discovery, authorization, token redemption, audience validation, refresh behavior, and exact error responses with each supported client.

6. Treat deprecations as an observability task

Deprecations are easier to manage when you know who still uses the old path. Break telemetry down by transport, protocol version, client, and capability. Set a migration threshold, notify affected users, and keep a compatibility test until the deprecation window closes.

Migration checklist

• Read the official specification and SDK notes for the version you are adopting.
• Test stateless requests across multiple server instances.
• Remove hidden dependence on transport session state.
• Update gateway routing and authorization to use the new request headers safely.
• Test catalog cache freshness and deterministic ordering.
• Instrument Tasks as a lifecycle rather than one request duration.
• Test OAuth discovery, issuer, audience, PKCE, and client metadata behavior.
• Measure deprecated transport and capability usage before setting a removal date.

Frequently asked questions