MCP Protocol Version Mismatch (Unsupported protocol version, -32022): How to Fix It (Claude Code, Inspector, SDKs)

A protocol version mismatch means your MCP client and server do not share a spec revision they both accept. Since the 2026-07-28 revision, there is no initialize handshake: every request names its version, and a server that does not support it returns UnsupportedProtocolVersionError (code -32022) with a list of versions it does support. The fastest fix is to let the client negotiate automatically (the default in the official SDKs) instead of pinning one version, or to update whichever side is older.

Checked against: the Versioning and Compatibility page and changelog of the 2026-07-28 spec, the TypeScript SDK troubleshooting guide and Claude Code's MCP docs on 2 November 2026 (TypeScript @modelcontextprotocol/server 2.4.0, Python mcp 2.3.0). eSEOspace did not run these steps.

What this error means

The 2026-07-28 changelog made MCP stateless. It removed the initialize handshake, and every request carries its protocol version in _meta. On HTTP the same version travels in an MCP-Protocol-Version header. The versioning page says a server that does not implement the requested version "MUST respond with an UnsupportedProtocolVersionError listing the versions it does support." Its example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": { "supported": ["2026-07-28", "2025-11-25"], "requested": "1900-01-01" }
  }
}

On Streamable HTTP this comes with 400 Bad Request. A related -32020 HeaderMismatch error means the header and the body named different versions.

The bigger source of trouble is mixing eras. The versioning page's compatibility matrix says:

"Legacy clients have no fall-forward mechanism," the page notes. In 2025-era revisions, mismatches looked different: the 2025-11-25 lifecycle page had the server reply with another version, and a client that did not support it "SHOULD disconnect."

Quick fix

1. Read the supported list in the error, if you got one. It tells you exactly which versions the server accepts.
2. Remove any version pin in your client and use automatic negotiation.
3. Update the older side. The official TypeScript and Python SDKs at v2 speak both eras as clients.
4. If you own a modern-only server with old clients, add legacy support (the SDKs call it dual-era) until those clients upgrade.
5. Retest with the MCP Inspector, setting its Protocol Era to auto.

Fix by client / OS

Claude Code

Claude Code's MCP docs describe two client runtimes. The v2 runtime, built on TypeScript SDK 2.0, asks HTTP and stdio servers whether they support 2026-07-28 and uses it with those that do. If a server breaks on that probe, set MCP_PROTOCOL_NEGOTIATION=legacy to skip it, or MCP_SDK_GENERATION=v1 to use the 1.x-based runtime. Per the environment variables page, the first needs Claude Code v2.1.221 or later and the second v2.1.218 or later.

TypeScript client (SDK v2)

The troubleshooting guide lists SdkError: ERA_NEGOTIATION_FAILED message tails. The most common is "the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode)." Its fix:

const client = new Client({ name: 'app', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
await client.connect(transport);
console.log(client.getProtocolEra()); // "legacy" or "modern"

The guide adds that a 401 or 403 during the probe is not a version problem.

Python client (SDK v2)

The Python SDK's protocol versions page says mode="auto" is the default: one server/discover probe, then fallback. mode="legacy" forces the initialize handshake. Passing a 2025 version string as a pin raises ValueError: ... '2025-06-18' is a handshake-era version; use mode='legacy'.

MCP Inspector

Each server has a Protocol Era setting of legacy, auto or modern, per the Inspector protocol eras page. legacy is the default. The CLI accepts --protocol-era <legacy|auto|modern> for one run. See MCP Inspector connection errors.

Where to find the logs

• Claude Code: claude --debug-file /tmp/claude-debug.log; unrecognized values for the two variables above are logged as warnings.
• VS Code: MCP: List Servers > Show Output.
• Claude Desktop: ~/Library/Logs/Claude/mcp*.log on macOS, %APPDATA%\Claude\logs on Windows, per the MCP debugging guide.
• Your server: log the MCP-Protocol-Version header and the _meta version on each request.

If it still fails

• 400 with an empty body. A legacy server or a proxy, not a modern error. A dual-era client falls back; a modern-only client cannot.
• Probe hangs on stdio. The spec says dual-era clients treat a non-modern error or timeout as legacy. Check that your server writes nothing but JSON-RPC to stdout; see stdout logging breaks the server.
• Method not found after connecting. You called a method from the other era. See -32601 method not found.
• Version lookup. Our MCP spec version explorer and error code lookup list what changed in each revision.

Next step

If you maintain a server that must serve both 2025 and 2026 clients, eSEOspace's MCP development team can help plan a dual-era rollout. For the background, read our versioning and deprecation guide.

Frequently asked questions