TL;DR: The MCP 2026-07-28 spec shipped July 28, 2026 and is wire-incompatible with all prior versions. It introduces three breaking changes: stateless transport replaces persistent connections, Client ID Metadata Documents replace Dynamic Client Registration, and Roots, Sampling, and Logging are deprecated. Teams running live MCP servers must update their transport layer, swap DCR flows for metadata document lookups, and migrate logging to direct server-side mechanisms before the old APIs are removed.
Key Takeaways
- Wire-incompatible as of 2026-07-28: Old session-handshake servers fail immediately with compliant clients. There is no negotiated fallback.
- Client ID Metadata Documents replace Dynamic Client Registration: The client hosts a metadata document; the server fetches and validates it, removing the server-side credential store entirely.
- Stateless transport is native infrastructure: Servers now work behind standard load balancers and HTTP caches without session-affinity workarounds.
- SDKs shipped with the spec: Migration tooling exists today; no hand-rolling required.
- Migration pressure is immediate: The spec is live, the breakage is live, and there is no grace period.
Introduction
The MCP 2026-07-28 spec shipped July 28, 2026 and is wire-incompatible with all prior versions. If your server still runs the old stateful session handshake, it fails with every compliant client right now. This article covers what changed, how stateless transport works, what Client ID Metadata Documents require in practice, which primitives are deprecated, and provides a concrete before-and-after checklist to migrate without downtime. One warning upfront: the most dangerous failure mode is not the one that crashes your server.
What exactly broke in the 2026-07-28 MCP spec?
The 2026-07-28 spec removes the stateful session handshake, replaces Dynamic Client Registration with Client ID Metadata Documents, deprecates three core primitives, and is wire-incompatible in both directions with all prior versions.
Four breaking changes define this revision:
- Stateless transport. The session handshake is gone. The spec describes this as "making agent infrastructure work like the rest of the web: stateless, cacheable, routable, and globally accessible".
- Client ID Metadata Documents. Dynamic Client Registration is replaced. Clients host a metadata document; servers fetch and validate it.
- Response caching and routability as first-class properties. These were impossible under the stateful model; they are native transport behaviors under 2026-07-28.
There is no negotiated fallback.
Table 1: MCP Transport Layer Changes, Pre- vs. Post-2026-07-28
| Component | Pre-2026-07-28 | Post-2026-07-28 |
|---|---|---|
| Transport | Stateful session handshake required | Stateless; no session negotiation |
| Auth registration | Dynamic Client Registration | Client ID Metadata Documents |
| Response caching | Not supported | First-class transport property |
| Roots primitive | Core spec | Deprecated |
| Sampling primitive | Core spec | Deprecated |
| Logging primitive | Core spec | Deprecated |
| Load balancer support | Requires custom workarounds | Native; no workarounds needed |
How do Client ID Metadata Documents replace Dynamic Client Registration in practice?
Client ID Metadata Documents shift credential issuance from server-side to client-side: the client hosts a metadata document, and the MCP server fetches and validates it during the auth handshake, eliminating the need for a server-side credential store.
Under Dynamic Client Registration, the server issued and stored credentials on demand, a stateful operation that required the server to maintain a credential store. Under the 2026-07-28 spec, the client hosts a metadata document and the server validates it on fetch. This removes the server-side credential store entirely.
Migration steps: 1. Remove or disable the /register endpoint on your server. 2. Confirm your client toolchain publishes a compliant metadata document. 3. Update server auth middleware to fetch and validate the document URL instead of checking stored credentials. 4. Test with a compliant client before deprecating the old endpoint.
How do I migrate an existing MCP server to stateless transport without downtime?
Update to the official SDK, strip session-handshake initialization, replace deprecated primitive dependencies, disable Dynamic Client Registration, and run old and new transport handlers behind a version-routing proxy during the transition window.
The dangerous transition state is not a hard error. A partially migrated server can silently accept requests the old handshake would have rejected, appearing operational while processing unauthenticated or malformed client contexts. This failure mode surfaces under real agent workloads, not in controlled tests where client behavior is predictable.
Phase 1, SDK and transport:
- [ ] Upgrade to the 2026-07-28-compatible SDK
- [ ] Remove session-handshake initialization logic from server startup
- [ ] Verify server returns no session token on connection
Phase 2, Auth: -
[ ] Disable or tombstone the /register endpoint
- [ ] Add metadata document fetch-and-validate middleware
- [ ] Confirm client metadata documents are reachable from your server's network
Phase 3, Deprecated primitives:
- [ ] Audit all handlers for roots, sampling, and logging usage
- [ ] Replace logging with structured log forwarding at the infrastructure layer
- [ ] Replace sampling with direct LLM API calls or a dedicated sampling service
- [ ] Replace Roots with explicit resource URI parameters in tool definitions
Phase 4, Validation:
- [ ] Run a compliant 2026-07-28 client against the migrated server in staging
- [ ] Instrument auth middleware to log rejected metadata documents explicitly; this surfaces the silent failure mode
- [ ] Monitor production for unauthenticated context errors in the first 48 hours post-migration
Adding explicit auth rejection logging before deployment rather than after is, as a practical rule of thumb used in this guide, the step most likely to prevent silent failures that pass smoke tests and appear in production.
Should teams adopt response caching and stateless load balancing immediately after the 2026-07-28 migration?
Response caching is safe to adopt immediately for read-only tool responses, and stateless load balancing should be confirmed with a multi-instance smoke test once Phase 1 is complete. As of July 2026, these are first-class transport properties of the spec, not experimental features.
Under the old model, multiple server instances required sticky sessions. Under 2026-07-28, any instance handles any request, the same way a REST API does. The Hacker News thread on the spec notes this creates "an easier path for people to use open-source MCP servers."
Adoption guidance:
- Response caching: Safe immediately for read-only tool responses. Do not cache tool calls with side effects.
- Load balancer config: Review session-affinity rules after Phase 1 and confirm with a multi-instance smoke test.
- Extensions framework: Worth evaluating once core migration is stable; do not block migration on it.
- SDK compatibility: SDKs supporting 2026-07-28 shipped alongside the spec; verify your installed version is listed as 2026-07-28-compatible in that SDK's own changelog.
FAQ
Q1: What exactly broke and what still works? Three components broke with the 2026-07-28 release: the stateful session handshake, Dynamic Client Registration, and the Roots, Sampling, and Logging primitives. Tool definitions and resource URI patterns that do not depend on those components carry forward. Review your implementation against the full specification to confirm which handlers are unaffected.
Q2: What happens to clients still using the old session handshake? They fail at the transport layer with a hard incompatibility, not a degraded experience. Update the client SDK to a 2026-07-28-compatible version to resolve it.
Q3: Is there a negotiated fallback or grace period? No. The spec is live and there is no negotiated fallback. Servers and clients must both be updated to the 2026-07-28 spec to communicate successfully.
Conclusion
Wire-incompatible means no negotiated fallback, no grace-period handshake, and no quiet coexistence. The architectural payoff is real: stateless transport, native cacheability, and standard load balancer support remove entire categories of operational complexity. The migration risk most likely to catch teams off guard is the silent one, a half-migrated server that accepts requests, returns responses, and passes smoke tests while quietly failing to validate client context.
Instrument auth rejection logging before deployment. Run Phase 4 validation in staging before any production traffic hits the new transport.
The breakage is live as of July 28, 2026. The SDKs are ready. Start with Phase 1: upgrade the SDK, strip the session handshake, and instrument auth logging.
Learn from me
Claude Code in Practice, my Maven cohort. Master Claude Code from fundamentals to advanced orchestration: skills, subagents, hooks, MCP, and production automation. Join the next cohort →
Hire us
Traversaal.ai. We're a team of forward deployed engineers solving the toughest AI problems for Fortune 100 companies: document intelligence, agentic data platforms, and real-time web intelligence, deployed in production. Work with our team to deploy your next agentic ecosystem. Talk to Traversaal.ai →
Join us
Want to solve these problems with us? We're always looking for forward deployed engineers who want to ship production AI. jobs@traversaal.ai
