Migrate Your MCP Server to the Stateless Spec Now

MCP's 2026-07-28 spec drops session state entirely - the biggest protocol change since launch. Here's what actually changed, what breaks, and where to start.

Cover art for Migrate Your MCP Server to the Stateless Spec Now

The MCP spec that shipped July 28 removed the session handshake that every MCP server has run on since the protocol launched. No deprecation grace period, no soft landing - the 2026-07-28 spec removes protocol-level sessions entirely: no more initialize handshake, no more Mcp-Session-Id header, no more GET stream endpoint. Every request is now a single, fully self-contained HTTP POST. If you have a remote MCP server in production, that change has already landed. And on August 22, the lead maintainers published an updated roadmap covering the next spec release and beyond

  • which means the window for treating this as a future concern is closed.

MCP's Python and TypeScript SDKs see close to 97 million monthly downloads. A lot of teams are running servers they built against the old stateful transport and may not realize the spec underneath them changed. This post is for them.

What the stateless change actually removes

The headline change is a stateless protocol core: MCP moves from a bidirectional stateful protocol to a request/response stateless one. It was one of the most requested changes from developers who wanted MCP servers that scale and behave like any other HTTP workload.

Before this release, the problem looked like this: running remote MCP servers required shared Redis session stores or complex gateway-level packet inspection, introducing massive latency and operational costs. Teams who tried to scale horizontally behind a load balancer had to either pin sessions to specific instances (which defeated the purpose of horizontal scaling) or externalize state to a shared cache. Both paths added infrastructure that had nothing to do with what the agent was actually trying to do.

Now every request is self-describing and independent. Protocol version, client info, and client capabilities that used to be exchanged once at connection setup now travel in a _meta field inline on every single request.

The practical consequence: each request now carries what a server needs to handle it, so any instance can answer any request and you scale an MCP server the way you scale an ordinary web service.

tools/list, prompts/list, resources/list, and resources/read now carry ttlMs and cacheScope, with deterministic ordering. A stable tool catalog keeps upstream prompt caches stable across reconnects - which is a real token-cost line item. Cache your tool list for the declared window and you stop paying to re-fetch it on every connection.

97Mmonthly SDK downloadsacross Python and TypeScript SDKs
6xtoken reductionfrom OpenAI's Harness optimization on the same agent loop
12 monthsminimum runwaybefore Roots, Sampling, or Logging can be removed

What the new roadmap adds on top

The new roadmap, published August 22 by lead maintainers David Soria Parra and Den Delimarsky, has five priorities: messaging primitives, HTTP transport, agent identity, improved primitives, and SDK experience. Together, they describe MCP growing from a standard tool-call envelope into infrastructure for long-running, delegated work.

The piece that matters most for teams who want to run agents inside corporate environments is Enterprise-Managed Authorization (EMA). EMA is a direct response to feedback from organizations that could not adopt MCP without central IT control over which servers employees connect to. Without it, MCP adoption in any organization with a real security team stalls at the POC stage. Authorization now aligns with production OAuth 2.0 and OIDC deployments, so MCP servers connect to enterprise identity systems like Entra or Okta without workarounds.

The other first-class addition is MCP Tunnels. MCP tunnels connect Claude to MCP servers inside a private network without exposing them to the public internet. Teams can bring internal tools to Claude with no inbound firewall rules, no public endpoints, and no IP allowlisting on the origin. That one change removes the most common blocker for teams trying to connect internal tools to an external agent host.

The roadmap does not announce that all of this is available. Some foundations shipped in the 2026-07-28 specification; other parts are extensions, open design work, or IETF drafts. Developers should take the direction seriously without treating the diagram as a compatibility promise.

What actually breaks, and what does not

This is where most coverage gets it wrong. The spec change is not a cliff.

Area Status Deadline
initialize handshake Removed (not deprecated) Already gone
Mcp-Session-Id header Removed (not deprecated) Already gone
Roots Deprecated, still works Earliest removal: July 2027
Sampling Deprecated, still works Earliest removal: July 2027
Logging Deprecated, still works Earliest removal: July 2027
OAuth 2.1 / issuer validation New requirement Migrate now - security risk

Existing servers do not break - nothing broke on July 28 - but teams that adopted the experimental 2025 Tasks API must migrate, and everyone should plan SDK upgrades within the deprecation windows.

The TypeScript SDK ships an automated codemod (v1-to-v2) that handles much of the mechanical refactoring; Python v2 has a dedicated migration guide; Go and C# migrations are gentler, with no package split.

The one place to move fast: the authorization hardening - iss validation and application_type registration - carries real security implications independent of the stateless migration timeline. If you are running a remote MCP server and have not reviewed your OAuth flow against the new spec, that is the item to do this week.

Honor ttlMs on tools/list. Cache the tool list for the declared window instead of refetching per connection. It costs nothing to implement and saves real tokens at scale.

Beagle in action#platform-eng, 10:42am
The ask
'do we need to do anything for the MCP stateless spec?'
Beagle drafts
reads the 2026-07-28 changelog and your team's server SDK version, drafts a gap summary: handshake removal is a non-issue on your hosted gateway, but the OAuth issuer validation is unaddressed
You approve
you approve the reply with the two-item action list; the thread closes without a meeting
Do this in your workspace

The practical migration checklist

If a teammate like Beagle pulled the key steps from the AAIF migration guide into a single Slack thread, this is what it would say:

  • New servers: build them stateless-native from day one; leave vendor-supplied servers to their vendors' timelines.

  • Existing servers: stop sending initialize as a required step. Issue self-contained requests against 2026-07-28 servers. Do not assume a pinned server instance. Design for any request reaching any instance behind a load balancer.

  • Auth: track OAuth 2.1 / OIDC discovery and issuer validation requirements, and evaluate EMA if you serve enterprise customers.

  • Deprecations: if you use Roots, Sampling, or Logging, begin migrating to the recommended alternatives. The earliest removal window is July 2027, but earlier is better.

  • SDK check: beta SDKs targeting the 2026-07-28 release candidate are already available for Python, TypeScript, Go, and C#.

One broader thing worth noting: this spec cycle is not happening in isolation. On August 20, OpenAI open-sourced Harness - the core execution framework powering Codex - under the Apache 2.0 licence, allowing developers to freely modify, embed, and commercialize it.

Harness manages the execution loop for AI agents, including task comprehension, long-conversation memory retention, real-time event streaming, tool invocation, interruptibility, status synchronization, and human-in-the-loop approval workflows.

Real-world tests show that with Harness optimization, the GPT-5.6 Sol model's score on the ARC-AGI-3 benchmark surged from 13.3% to 38.3%, while token consumption decreased sixfold. That is the same efficiency problem the stateless MCP spec addresses at the protocol level - the whole stack is moving in the same direction at once.

Running a remote MCP server
Without Beagle
every client pins to one instance via session ID; horizontal scaling requires a shared Redis store or sticky routing; load balancers need custom packet inspection to route correctly
With Beagle
each request is a self-contained HTTP POST; any instance answers any request; standard load balancers and serverless platforms work without modification

MCP stateless spec: common questions

What did the MCP 2026-07-28 spec actually change?

The MCP 2026-07-28 specification makes the protocol stateless at its core and adds routing, caching, and authorization changes built around that shift. The session handshake and session ID header are removed entirely. Every request now carries its own protocol version and client capabilities inline. MCP servers can now scale horizontally like any ordinary HTTP service.

Does my existing MCP server break when clients upgrade to the new spec?

A v2 server answers both the legacy initialize handshake and the new server/discover method, so existing clients keep working. Nothing forces a release-day cutover. The risk is the inverse: if you leave an old server running, new clients that only speak the stateless spec may not initialize correctly against it.

What is the most urgent thing to fix in the new MCP spec?

Authorization hardening. The 2026-07-28 spec mandates issuer verification per RFC 9207 - public clients must validate the iss parameter on authorization responses - and Resource Indicators per RFC 8707, so clients explicitly specify which MCP server a token is intended for. These close real attack vectors in multi-server architectures and should be addressed before scaling.

What does the August 22 MCP roadmap add?

The August 22 roadmap sets the direction for protocol work over the coming months and was developed by the core maintainers together with the community and working groups. The headline additions are better agent-to-agent messaging primitives, formal agent identity, and SDK quality improvements - positioning MCP as infrastructure for delegated, long-running work rather than simple tool calls.

If I only use hosted MCP integrations, do I need to do anything?

Not directly - a hosted gateway handles the protocol-level migration for you. But it is worth confirming with your vendor that their gateway has been updated to the 2026-07-28 spec, and it is worth reviewing whether your OAuth flow meets the new issuer validation requirements regardless.

Or just watch me work

Point me at your website.

I will read up on your business and come back with what I would run for you. No account, no card, about a minute.

I only read what is public. Nothing is saved to your name until you say so.

Keep reading

Beagle does this work for you, in your Slack.1,000 free credits. No card.Hire Beagle