Migration guide
From sessions to self-contained requests.
Reviewed July 29, 2026 · 7 minute read
The 2026-07-28 revision removes the initialization handshake as a prerequisite and makes protocol context explicit on every request. Migration is therefore more than renaming an RPC: routing, capability checks, authentication and error handling must become request-scoped.
1. Add the new path without deleting fallback
Let updated clients send 2026-07-28 requests while older clients continue negotiating a supported legacy version. Make the distinction explicit in transport tests. A client that pins 2026-07-28 should fail clearly instead of silently entering a session path.
2. Implement server/discover
Return supportedVersions, capabilities and optional instructions. Discovery works over HTTP and stdio, but a client that already knows the version may call another method directly.
3. Move client context into params._meta
Every request needs io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. The latter is still required when empty. Client info is recommended for diagnostics, never authorization.
4. Validate standardized headers
For HTTP, require MCP-Protocol-Version to match the body metadata and MCP-Method to match the JSON-RPC method where applicable. Treat a mismatch as a client error rather than guessing.
5. Remove stateful assumptions
Do not depend on Mcp-Session-Id, a standalone GET stream, DELETE teardown or Last-Event-ID. Authenticate and authorize each request. Replace out-of-band server-to-client flows with the current request/response mechanisms or a negotiated legacy path.
6. Test negative cases
- Unsupported version returns the standardized
-32022JSON-RPC error. - Header/body disagreement returns
-32020. - A missing required client capability returns
-32021. - Removed methods return Method Not Found.
- Legacy clients still negotiate only where deliberately supported.
Run a trace before integration tests
Paste representative request headers and messages into the MCP 2026 validator. Then test real authentication, streaming, timeouts and fallback using your SDK.