# MCP 2026-07-28: what changed and how to migrate a server

URL: https://developertoolkit.ai/en/ecosystem/mcp/spec-2026-07-28/
Description: MCP 2026-07-28 drops the handshake and sessions and adds server/discover. What breaks in a custom server, how to migrate it, and how to test both eras.

MCP specification 2026-07-28 makes the protocol stateless: the `initialize` handshake and the `Mcp-Session-Id` header are gone, every request carries its protocol version and client capabilities in `_meta`, and servers must implement `server/discover`. A custom server migrates by upgrading to the v2 SDK, replacing session state and server-initiated requests, and serving both protocol eras side by side.

Your team's internal MCP server wraps the deploy API. It keeps a per-session cache keyed on `Mcp-Session-Id`, asks the user to confirm a rollback through `elicitation/create`, and logs through `logging/setLevel`. All three are removed or deprecated in 2026-07-28. Claude Code already negotiates the new revision with HTTP servers by default, and Codex still does not (0.162.1, checked 2026-10-12), so the same server has to answer both. This page is for the developer who owns that server and for the tech lead who signs off the migration.

Checked on 2026-09-26 against the [2026-07-28 changelog](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2026-07-28/changelog.mdx), the [maintainers' release post](https://blog.modelcontextprotocol.io/posts/2026-07-28/) (2026-07-28), the TypeScript SDK 2.1.0 and Python SDK 2.2.0 documentation, Claude Code 2.1.283 and codex-cli 0.157.1. The Claude Code and Codex rows of the client table, and the Server Cards paragraph, were re-checked on 2026-10-12 against Claude Code 2.1.296 and codex-cli 0.162.1. Cursor's MCP protocol support was not verified on 2026-09-26; test it in the app (see the Cursor tab). This page assumes you already run a server built as in [Building your own MCP server](/en/ecosystem/mcp/custom-mcp-development/).

## What you get from migrating a server to MCP 2026-07-28

- Every breaking change, what it breaks and what replaces it.
- Which clients speak the new revision, and why you keep serving the old one.
- A TypeScript migration, step by step, plus the Python equivalents.
- A smoke test per protocol era that fails CI when either breaks.
- Four copy-paste prompts: audit, migrate, call, and test.
- A sign-off checklist for the migration pull request.

## What changed in MCP 2026-07-28?

The maintainers summarise the release as "a stateless protocol core, Multi Round-Trip Requests, header-based routing, cacheable list results, authorization hardening, a formal extensions framework, and updated Tier 1 SDKs" ([MCP blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/), 2026-07-28). The release candidate was locked on 21 May 2026. For a server author, the changelog reduces to the rows below.

| Change in 2026-07-28 | What it breaks in your server | Replace it with |
| --- | --- | --- |
| `initialize` / `notifications/initialized` removed | Code that reads client capabilities or client info once, at connect time | Per-request `_meta` keys: `io.modelcontextprotocol/protocolVersion`, `clientCapabilities`, and optionally `clientInfo` |
| `server/discover` added, and servers **must** implement it | A hand-rolled server that has no handler for it | The v2 SDKs answer it for you |
| `Mcp-Session-Id` and protocol sessions removed | State keyed on the session id: caches, auth context, multi-step flows | Explicit handles returned by one tool and passed back as arguments to the next, or a signed `requestState` |
| Server-initiated `sampling/createMessage`, `elicitation/create`, `roots/list` replaced by Multi Round-Trip Requests | A tool that pauses mid-call to ask the user something | Return `resultType: "input_required"` with `inputRequests`; the client retries the call with `inputResponses` |
| Every result carries a required `resultType` | Hand-built JSON-RPC results | `"complete"` for ordinary results (the SDKs set it) |
| HTTP GET stream and `resources/subscribe` replaced by `subscriptions/listen` | Change notifications pushed on the standalone stream | One opted-in stream per client, tagged with a subscription id |
| `ping`, `logging/setLevel` and `notifications/roots/list_changed` removed | Health checks built on `ping`, session-wide log levels | Per-request `io.modelcontextprotocol/logLevel` in `_meta`; no logs are sent when it is absent |
| SSE resumability (`Last-Event-ID`) removed | Long calls that relied on the client resuming a broken stream | The client re-issues the request, so make tool calls safe to repeat |
| `Mcp-Method` and `Mcp-Name` headers required on Streamable HTTP POSTs | Gateways and WAF rules that strip unknown headers | Allow the headers through; route and rate-limit on them |
| List results carry `ttlMs` and `cacheScope`; `tools/list` should be in a deterministic order | Tool lists built from an unordered map | A stable sort, so clients and prompt caches see the same list |
| Tasks moved to the `io.modelcontextprotocol/tasks` extension | Code on the experimental core tasks API | Poll with `tasks/get`, send input with `tasks/update`; `tasks/list` is gone |
| Resource-not-found error code changed from `-32002` to `-32602` | Clients or tests that match on the old code | The JSON-RPC Invalid Params code |

Four features are **deprecated but still work** for at least twelve months under the new deprecation policy: Roots, Sampling, Logging, and the HTTP+SSE transport. Dynamic Client Registration is deprecated in favour of Client ID Metadata Documents, and clients must now validate the `iss` parameter when an OAuth authorization response carries one. New code should not adopt any of the deprecated features.

The extensions framework also formalises **MCP Apps**: interactive UI that a server returns for rendering in a sandboxed iframe. Its SDK is `@modelcontextprotocol/ext-apps` (npm `2.0.0`, the `latest` tag on 2026-09-26, published 2026-09-08), and its README lists Claude, ChatGPT and VS Code as supported clients. Its extension id is `io.modelcontextprotocol/ui`. Extensions stay off until both sides declare them, so fall back to core behaviour otherwise. In codex-cli 0.157.1 and 0.162.1 the `enable_mcp_apps` feature is `under development` and off (`codex features list`, checked 2026-10-12), so a tool that returns an App must still return a useful text result.

Another extension, SEP-2127 MCP Server Cards, reached Final on 2026-10-06 (Extensions Track, extension id `io.modelcontextprotocol/server-card`). It standardises a self-contained format that describes a server before a client connects, with its available transports, protocol versions and connection guidance. The spec revision is still 2026-07-28 (checked 2026-10-12), and no step in this migration depends on a server card.

## Which clients speak MCP 2026-07-28 today?

Your server does not choose the protocol; the client does. A client that supports both eras probes first (with `server/discover`, or on HTTP with a first modern request) and falls back to `initialize` when the server gives no modern answer. A client that knows only the old era sends `initialize` and nothing else. Clients differ, so plan for both eras on the same endpoint.

| Client | Speaks 2026-07-28? | How to force either era for a test |
| --- | --- | --- |
| Claude Code | Yes with HTTP servers, by default on the v2 client runtime (all install types by v2.1.274). Stdio servers negotiate it by default from v2.1.292 (both release channels on 2026-10-17), on every install including Bedrock, Google Cloud and Foundry; in 2.1.283 they stayed on the older handshake unless you opted in. claude.ai connectors negotiate it by default from v2.1.295 (`latest` only) on installs that fetch no flags | `MCP_PROTOCOL_NEGOTIATION=legacy` skips the probe for every server and opts stdio servers out; in 2.1.283, `auto` probed stdio servers too |
| Codex 0.162.1 | No. `mcp_2026_07_28` is `under development` and off (`codex features list`, checked 2026-10-12; the same in 0.157.1) | `codex --enable mcp_2026_07_28` turns the unfinished feature on for one run. Treat it as a preview, not a gate |
| Cursor | Not verified on 2026-09-26 | Test in the app after each Cursor update |

SDK status on 2026-09-26: the TypeScript v2 packages `@modelcontextprotocol/server` and `@modelcontextprotocol/client` are at 2.1.0 (npm), the v1 package `@modelcontextprotocol/sdk` is at 1.30.1 and gets fixes for at least six months after v2's release, and PyPI `mcp` is at 2.2.0. The maintainers report "close to half-a-billion downloads a month" across the Tier 1 SDKs (TypeScript, Python, Go and C#) in the same [release post](https://blog.modelcontextprotocol.io/posts/2026-07-28/), a maintainer-reported figure.

## Does your MCP server need to change?

The SDKs keep serving 2025-era clients, so the migration is mostly about what your own code assumes. Find your server's row.

| Your server today | Work required |
| --- | --- |
| Stateless tools on the TypeScript v1 SDK, stdio | Upgrade to v2 and switch to `serveStdio`. Small: the codemod does most of it |
| Stateless tools on the TypeScript v1 SDK, Streamable HTTP with `sessionIdGenerator: undefined` | Upgrade to v2; the default `createMcpHandler` maps onto this setup directly |
| Anything keyed on the session id | Redesign that state as explicit handles or `requestState`. This is the real cost |
| Tools that call `elicitInput`, `createMessage` or `roots/list` | Rewrite them to return `input_required` (TypeScript) or use `Resolve(...)` parameters (Python) |
| HTTP+SSE transport | Move to Streamable HTTP. The v2 server does not serve SSE |
| Python on `mcp` 1.x | Pin `mcp<2` today (the SDK's own advice; 1.29.1 is the last 1.x on 2026-09-26), then port to `MCPServer` (below) |
| Hand-written JSON-RPC, no SDK | Implement `server/discover`, `_meta` parsing, `resultType` and the new headers yourself, or move to an SDK |

## Migrate a TypeScript MCP server to 2026-07-28

The TypeScript SDK splits the migration in two. A codemod moves your code from the v1 package to the v2 packages. Speaking 2026-07-28 is then an explicit opt-in, because a hand-constructed v2 server connected straight to a transport keeps speaking the 2025 protocol it was written for.

1. **Inventory what the server assumes.** Run the audit prompt below before you change anything. You want a list of every read of a session id, every server-initiated request, every log call and every tool whose result depends on an earlier call.

2. **Run the codemod from the package root**, so that it also rewrites imports in tests and scripts:

   ```bash
   npx @modelcontextprotocol/codemod@latest v1-to-v2 .
   ```

   It handles the mechanical renames from `@modelcontextprotocol/sdk` to `@modelcontextprotocol/server` and `@modelcontextprotocol/client`. It does not adopt 2026-07-28 for you.

3. **Switch to a per-request entry point.** Build the server in a factory, because the 2026 path builds a fresh instance per request (HTTP) or per connection (stdio).

   ```ts
   // v1: new McpServer(...) + await server.connect(new StdioServerTransport())
   import { McpServer } from '@modelcontextprotocol/server';
   import { serveStdio } from '@modelcontextprotocol/server/stdio';
   import * as z from 'zod/v4';

   function buildServer() {
     const server = new McpServer({ name: 'deploy-tools', version: '2.0.0' });
     server.registerTool(
       'get_release',
       { description: 'Read one release by id', inputSchema: z.object({ releaseId: z.string() }) },
       async ({ releaseId }) => ({ content: [{ type: 'text', text: await readRelease(releaseId) }] }),
     );
     return server;
   }

   serveStdio(buildServer); // serves 2026-07-28 and, by default, 2025-era openings
   ```

   For HTTP, use `createMcpHandler(buildServer)` from `@modelcontextprotocol/server`. On Node frameworks, wrap it with `toNodeHandler` from `@modelcontextprotocol/node`, for example `app.all('/mcp', toNodeHandler(handler))`. The default `legacy: 'stateless'` also serves 2025-era clients per request.

4. **Replace session state.** A cache or auth context keyed on the session id has no key anymore. Return an explicit handle from the tool that creates the state (for example `releaseId`) and make the next tool take it as an argument; the model sees the handle and threads it through. For a multi-step flow inside one call, use `requestState`, and sign it with `createRequestStateCodec({ key })`, because the client echoes it back and it is untrusted input. The key must be at least 32 bytes and come from your secret store, never from source code.

5. **Replace server-initiated requests.** Where a tool called `elicitInput` or `createMessage`, it now returns `inputRequired(...)` and reads the answer from `ctx.mcpReq.inputResponses` on the retry. The same handler still runs for 2025-era clients through the SDK's legacy shim.

6. **Move logging off the protocol.** Log to `stderr` (never `stdout` on stdio) or to OpenTelemetry. `ctx.mcpReq.log()` sends nothing on a 2026 request unless the client set `logLevel` in `_meta`, and the SDK client does not set it by default.

7. **Sort `tools/list`.** Register tools in a fixed order, so that the list is identical on every request and client-side caches stay valid.

8. **Keep an old sessionful deployment running if you must.** Put a strict handler (`createMcpHandler(buildServer, { legacy: 'reject' })`) behind a branch on `isLegacyRequest(request)` and send legacy traffic to your existing v1 wiring until its clients are gone.

### Migrate a Python MCP server to 2026-07-28

PyPI `mcp` 2.x implements 2026-07-28 and serves both eras from the same `streamable_http_app()` or stdio server, with no flag to set. The changes land in your code:

- `pip install mcp` now installs 2.x. Pin `mcp<2` in every project that is not migrated yet, or an unpinned build upgrades it for you.
- `FastMCP` is now `MCPServer`: `from mcp.server import MCPServer`. Transport options such as `host`, `port` and `stateless_http` move from the constructor to `run()` and the app builders.
- `ctx.elicit()` and `ctx.session.create_message()` raise `NoBackChannelError` on a 2026 connection. Move the question into a parameter annotated with `Resolve(...)`, which asks over whichever mechanism the connection supports.
- The sealed `request_state` key is minted per process by default. Behind a load balancer, pass `RequestStateSecurity(keys=[...])` so that every replica can verify a retry.
- The v2 migration guide lists the experimental Tasks support as removed. Until you have confirmed Tasks extension support in the SDK version you pin, keep long-running work behind your own job id and a status tool.

**Copy-paste prompt: audit an MCP server for 2026-07-28 breakage**

```text
Audit this MCP server for MCP spec 2026-07-28 compatibility. Do not edit any file.
List, with file and line:
1. Every read of a session id (sessionId, Mcp-Session-Id, extra.sessionId, ctx.sessionId) and what state it keys.
2. Every server-initiated request: elicitInput / elicit, createMessage / sampling, roots/list.
3. Every logging call that goes through MCP (ctx.mcpReq.log, ctx.info, logging/setLevel) and every console.log on stdio.
4. Every use of ping, resources/subscribe, the HTTP GET stream, or the HTTP+SSE transport.
5. Every tool whose result depends on a previous call in the same session.
6. The SDK package and version from the lockfile.
For each item, name the 2026-07-28 replacement (explicit handle, requestState, input_required,
stderr or OpenTelemetry, subscriptions/listen, Streamable HTTP) and estimate the effort as S, M or L.
```

**Copy-paste prompt: migrate the server to the v2 SDK**

```text
Migrate this TypeScript MCP server to @modelcontextprotocol/server 2.x so it serves MCP 2026-07-28
and still serves 2025-era clients.
1. Run `npx @modelcontextprotocol/codemod@latest v1-to-v2 .` from the package root and show me the diff.
2. Move server construction into a buildServer() factory. Use serveStdio(buildServer) for stdio and
   createMcpHandler(buildServer) for HTTP, keeping the default legacy posture.
3. Replace every session-keyed state with an explicit handle returned by one tool and taken as an
   argument by the next. Do not invent a session store.
4. Replace elicitInput / createMessage calls with inputRequired(...) and read the answer from
   ctx.mcpReq.inputResponses. Sign any requestState with createRequestStateCodec.
5. Send logs to stderr. Register tools in alphabetical order.
Stop after each step, run the type check and the tests, and show me the result before continuing.
```

## Prove the server works in both protocol eras

A green dot in one client proves one era. The gate that matters connects twice, once pinned to 2026-07-28 and once on the 2025 handshake, and fails when either connection lists no tools, a known call breaks, or the two eras expose different tool names. Pin mode never falls back, so a server that silently serves only the old protocol fails the first connection instead of passing.

```js
// scripts/mcp-era-smoke.mjs (run: MCP_URL=http://localhost:3000/mcp node scripts/mcp-era-smoke.mjs)
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const url = new URL(process.env.MCP_URL ?? 'http://localhost:3000/mcp');
const modes = [{ pin: '2026-07-28' }, 'legacy'];

const names = [];

for (const mode of modes) {
  const client = new Client({ name: 'era-smoke', version: '1.0.0' }, { versionNegotiation: { mode } });
  await client.connect(new StreamableHTTPClientTransport(url));
  const { tools } = await client.listTools();
  console.log(`${client.getProtocolEra()}: ${tools.length} tools`);
  if (tools.length === 0) process.exitCode = 1;
  names.push(JSON.stringify(tools.map((t) => t.name).sort()));
  try {
    // a known call with a fixture id must succeed in both eras
    const result = await client.callTool({
      name: 'get_release',
      arguments: { releaseId: process.env.FIXTURE_ID ?? 'r-102' },
    });
    if (result.isError) process.exitCode = 1;
  } catch (err) {
    console.error(`${client.getProtocolEra()}: get_release failed`, err);
    process.exitCode = 1;
  }
  await client.close();
}

// both eras must expose the same tool names
if (names[0] !== names[1]) {
  console.error('tool lists differ between eras');
  process.exitCode = 1;
}
```

The expected output is one `modern` line and one `legacy` line with the same tool count, and exit code 0; a failed `get_release` call or differing tool names set exit code 1. An `ERA_NEGOTIATION_FAILED` error on the first line means the server never offered 2026-07-28. For tests without a socket, pass the handler's `fetch` to the transport (`fetch: (u, init) => handler.fetch(new Request(u, init))`), which serves the request in-process. In Python, `Client(mcp)` against the server object negotiates 2026-07-28 by default; pin a second test client to `mode="legacy"` to cover the old path.

To check a running server by hand without writing code, use the MCP Inspector CLI (`@modelcontextprotocol/inspector` 2.8.0 on 2026-09-26). It connects on the **legacy** era unless you say otherwise, so pass `--protocol-era` explicitly both times:

```bash
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --protocol-era legacy --method tools/list
```

Both commands should print the same tool names. For a stdio server, replace the URL and `--transport http` with the launch command, for example `node build/index.js`.

Then register the server in each agent you support and call one read-only tool. The commands differ per tool:

**Claude Code**

Register the local server, then compare the two eras. Claude Code probes HTTP servers for 2026-07-28 by default, and stdio servers too from v2.1.292:

```bash
claude mcp add --transport http deploy-tools http://localhost:3000/mcp
claude mcp list                                   # default: HTTP servers on 2026-07-28 where offered
MCP_PROTOCOL_NEGOTIATION=legacy claude mcp list   # force the older handshake
MCP_PROTOCOL_NEGOTIATION=auto claude              # before v2.1.292: also probe stdio servers, then call a tool
```

If the server works only with `legacy`, the bug is on its 2026 path. A stdio server that is also a [channel](https://code.claude.com/docs/en/channels) is not registered as a channel once it negotiates 2026-07-28 (by default from v2.1.292), because that revision cannot carry channel messages.

**Codex**

Codex 0.162.1 connects on the older protocol (`mcp_2026_07_28` is off, checked 2026-10-12), so a normal run tests your legacy path:

```bash
codex mcp add deploy-tools --url http://localhost:3000/mcp
codex mcp list
codex exec "Call the get_release tool with releaseId r-102 and print the raw result."
```

To try the unfinished 2026-07-28 client on one run, add `--enable mcp_2026_07_28`. It is `under development`, so a failure there is not yet a bug in your server.

**Cursor**

Add the server to `.cursor/mcp.json` (this shape comes from vendor READMEs and was not tested in Cursor):

```json
{
  "mcpServers": {
    "deploy-tools": { "url": "http://localhost:3000/mcp" }
  }
}
```

Which protocol revision Cursor negotiates was not verified on 2026-09-26. After a Cursor update, open the MCP settings, confirm that the server shows its tools, and ask the agent to call one read-only tool. Keep the dual-era smoke test as the gate, because it does not depend on Cursor's version.

In any of the three agents, this prompt proves the tool works end to end and shows you what the model received:

**Copy-paste prompt: call the migrated server from any agent**

```text
Using only the deploy-tools MCP server, call get_release with releaseId r-102.
Print the raw tool result, including resultType if it is visible, and list every MCP tool you called.
Do not call any tool that changes a release.
```

You should see exactly one `get_release` call and the release record. A confirmation prompt or an `input_required` round trip on a read-only tool means the tool asks for input it should not need.

**Copy-paste prompt: add the dual-era gate to CI**

```text
Add an MCP protocol gate to this repository.
1. Create scripts/mcp-era-smoke.mjs that connects to MCP_URL twice with @modelcontextprotocol/client:
   once with versionNegotiation { mode: { pin: '2026-07-28' } } and once with mode 'legacy'.
   Each run lists tools and calls get_release with a fixture id. Exit non-zero if either era fails,
   lists zero tools, or returns different tool names.
2. Add a CI job that starts the server locally on a random port, runs the script, and stops the server.
   Use only test credentials, set permissions: contents: read, and run it on pull requests without secrets.
3. Run the script once and show me the output.
```

## Sign off an MCP server migration

The migration is done when the evidence below is attached to the pull request, not when the code compiles. The server owner produces it; the tech lead who owns the team's MCP configuration signs off.

- [ ] The SDK is v2: `@modelcontextprotocol/server` 2.x, or PyPI `mcp` 2.x with an explicit version range.
- [ ] No code reads a session id; cross-call state travels as explicit handles or signed `requestState`.
- [ ] No tool sends a server-initiated request on the 2026 path; each question returns `input_required`.
- [ ] The dual-era smoke test passes in CI, with the same tool names in both eras.
- [ ] `tools/list` returns the same order on every call.
- [ ] Logs go to `stderr` or OpenTelemetry; nothing writes to `stdout` on stdio.
- [ ] Gateways, proxies and WAF rules pass `Mcp-Method`, `Mcp-Name` and `MCP-Protocol-Version`.
- [ ] Each supported agent was tried: Claude Code in both eras, Codex on its default, Cursor by hand.
- [ ] Rollback is written down: the previous release tag, and for Claude Code users `MCP_PROTOCOL_NEGOTIATION=legacy` (or `MCP_SDK_GENERATION=v1`) as the client-side escape hatch.

## What 2026-07-28 changes about context cost

The revision does not shrink your tool definitions, so the tokens each tool costs in the agent's context stay the same. What it changes is stability. A `tools/list` in a deterministic order, with a `ttlMs` freshness hint, lets a client cache the catalog and keeps the model provider's prompt cache stable across reconnects. A server that shuffles its tools on every request defeats both. Measure before and after with `/context` in Claude Code, and cut tools with the patterns in [reducing MCP token cost](/en/ecosystem/mcp/reducing-mcp-token-cost/).

**Traps when migrating to MCP 2026-07-28**

- **"The SDK upgrade migrated us."** A v2 TypeScript server connected with `server.connect(new StdioServerTransport())` still speaks only the 2025 protocol. Use `serveStdio` or `createMcpHandler`.
- **"Codex supports the new spec."** Not in 0.157.1 or 0.162.1 (checked 2026-10-12): `mcp_2026_07_28` is under development and off.
- **"`server/discover` is optional."** It is optional for clients to call and mandatory for servers to implement.
- **An Inspector check that passes on the old era only.** The Inspector connects as `legacy` unless you pass `--protocol-era modern`.
- **"Deprecated means removed."** Roots, Sampling, Logging and HTTP+SSE still work for at least twelve months; `ping` and `logging/setLevel` are removed now.
- **`mcp` without an upper bound in Python.** It resolves to 2.x today and renames `FastMCP`.
- **`requestState` trusted as server state.** The client echoes it back; sign it and check the expiry.

## What breaks after migrating to MCP 2026-07-28?

**`ERA_NEGOTIATION_FAILED: ... did not offer pinned protocol version 2026-07-28`.** The server still answers only `initialize`. Check that the entry point is `serveStdio` or `createMcpHandler`, not a direct `server.connect(...)`, and that no proxy in front of it answers `server/discover` with an error page.

**Logs stopped appearing.** On a 2026 request the server sends `notifications/message` only when the client put `logLevel` in `_meta`. Log to `stderr` or OpenTelemetry instead of relying on protocol logging.

**`NoBackChannelError` (Python) or a confirmation prompt that never shows.** The tool still sends a server-initiated elicitation. Return `input_required` in TypeScript, or move the question into a `Resolve(...)` parameter in Python.

**Retries fail with an invalid-params error behind a load balancer.** Each replica signs `requestState` with its own per-process key, so a retry that lands on another replica fails verification. Configure one shared key set (`createRequestStateCodec({ key })` in TypeScript, `RequestStateSecurity(keys=[...])` in Python) and rotate it like any other secret.

**Requests fail with `HeaderMismatch` (`-32020`) or never reach the server.** A gateway rewrote or dropped `Mcp-Method` or `Mcp-Name`. Pass both headers through and let the gateway route on them. If browser-based clients call the server, add `Mcp-Method`, `Mcp-Name` and `MCP-Protocol-Version` to `Access-Control-Allow-Headers`, because a browser blocks custom headers that the CORS preflight does not allow.

**The server works in Codex and fails in Claude Code.** Codex speaks 2025, Claude Code speaks 2026 with HTTP servers. Run `MCP_PROTOCOL_NEGOTIATION=legacy claude` to confirm, which also serves as the users' workaround, and fix the 2026 path with the smoke test above.

**A Rust stdio server exits as soon as a client connects.** Servers on the Rust SDK (rmcp) exit on any request before `initialize`, including the `server/discover` probe. The TypeScript client probes on a disposable sibling process for this reason. If you write your own client, probe the same way or pin `mode: 'legacy'` for that server.

**A client still matches the old resource error code.** Resource-not-found is now `-32602`, not `-32002`. Update tests that assert the old number.

## Where to go next with MCP 2026-07-28

- [Building your own MCP server](/en/ecosystem/mcp/custom-mcp-development/) — The server walkthrough this migration applies to: tools, resources, prompts and shipping.
- [MCP server connection issues](/en/ecosystem/mcp/mcp-connection-issues/) — Diagnose a server that fails in one agent and not in another, including protocol version problems.
- [MCP registries and gateways](/en/ecosystem/mcp/registry-and-gateways/) — Allowlist servers for an organization and route them through a gateway that passes the new headers.
- [Securing MCP servers](/en/ecosystem/mcp/mcp-security/) — Token scopes, OAuth issuer checks and what a server entry is allowed to run.
- [Introduction to MCP](/en/ecosystem/mcp/) — Where each agent stores servers, and how to add a remote server safely.
