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

Level 4: Build · 10 min · Updated 19 November 2026 · Path: Build MCP servers

By the end 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](https://ai-powered.com/academy/glossary/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

**Steps**

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.

```shell
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
```

**Watch out**

"Stateless protocol" doesn't mean "stateless app". The blog is explicit that dropping protocol sessions doesn't force your application to be stateless; it moves state into explicit handles that you must now protect like any other credential.

## Key takeaways

- 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

- Starting fresh instead? [Build your first MCP server](https://ai-powered.com/academy/build-mcp-servers/first-mcp-server) already targets 2026-07-28.
- Re-run the [security checklist](https://ai-powered.com/academy/build-mcp-servers/mcp-server-security-checklist): handles and auth changed.

## Sources

Official documentation, checked on 19 November 2026:

- [The 2026-07-28 specification release (MCP blog)](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
- [MCP architecture overview (modelcontextprotocol.io)](https://modelcontextprotocol.io/docs/learn/architecture)
- [Build an MCP server (modelcontextprotocol.io)](https://modelcontextprotocol.io/docs/develop/build-server)

Next lesson: [MCP server security checklist](https://ai-powered.com/academy/build-mcp-servers/mcp-server-security-checklist)
