Skip to content

Migrate your MCP server to the 2026-07-28 spec

Level 4: Build. About 10 min. Checked on 19 November 2026 against MCP spec 2026-07-28, @modelcontextprotocol/server 2.4.0.
Stage 4 of 4: Build

In this lesson you'll know which 2026-07-28 changes affect your server, update it without breaking older clients, and plan around the deprecation windows.

Your server has worked fine for a year. Then a client on the new spec connects and something's off: it never sends initialize, and your session-keyed state is empty. The July 2026 revision of MCP made the protocol stateless, and most tutorials on the web still describe the old handshake.

The good news: the official SDKs absorb most of it, and the old features keep working through a deprecation window of at least twelve months.

What changed

Before 2026-07-28

  • initialize / initialized handshake opens a session.
  • Mcp-Session-Id header carries session state.
  • Servers send elicitation, sampling and roots requests over a held-open stream.
  • Clients register for OAuth with Dynamic Client Registration.

From 2026-07-28

  • No handshake: every request carries protocol version, client identity and capabilities in _meta. Optional server/discover for capabilities up front.
  • No session ID. Streamable HTTP requests carry Mcp-Method and Mcp-Name headers, so gateways can route them.
  • Multi round-trip requests: the server answers resultType: "input_required", the client retries with inputResponses.
  • Client ID Metadata Documents (CIMD) replace DCR, which is deprecated.

Also new: cache hints (ttlMs, cacheScope) on list results, a deterministic order for lists, a single subscriptions/listen stream for change notifications, and a formal extensions framework (Tasks, MCP Apps and Enterprise-Managed Authorization are extensions).

Deprecated, with a window

  • Roots, Sampling and Logging still work "for at least twelve months"; new implementations shouldn't adopt them. Log to stderr (stdio) or OpenTelemetry instead of protocol logging.
  • The HTTP+SSE transport has a year-long off-ramp. Move to Streamable HTTP.
  • Dynamic Client Registration is deprecated in favour of CIMD, with no removal date given yet.

Migrate, step by step

  1. Update the SDK. The blog lists TypeScript, Python, Go and C# as Tier 1 for 2026-07-28, with Rust in beta. In TypeScript, serve stdio with serveStdio(createServer) so the same server answers new clients and clients that still open with initialize; wiring server.connect(new StdioServerTransport()) by hand only serves older clients.
  2. Remove session state. If you kept state per Mcp-Session-Id, mint an explicit handle in a tool result (a cart ID, a job ID) and have the model pass it back as a tool argument. Bind it to the authenticated user and make it unguessable.
  3. Replace server-initiated requests. Where you asked the user something mid-call (elicitation), return input_required and let the client retry with the answer.
  4. Check your gateway. If a proxy sits in front of your HTTP server, route on Mcp-Method and Mcp-Name instead of session affinity.
  5. Fix auth. Validate the issuer (iss) before redeeming an authorization code, set application_type if you support desktop or CLI clients with localhost redirects, and plan your move from DCR to CIMD.
  6. Test both eras. List tools with the MCP Inspector in the modern protocol era and again in the default legacy era.
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

In short

  • No handshake, no session ID: every request describes itself.
  • Old features keep working for at least twelve months; plan, don't panic.
  • Explicit handles replace session state; MRTR replaces server-initiated requests.

What to try next

Share this lesson

Lesson 2 of 6 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.