createmcps.com

Error

MCP error -32020: HeaderMismatch

Against MCP 2026-07-28 · verified 10 August 2026

A routing header and the request body are telling the server two different things. 2026-07-28 added this code precisely so the disagreement is reported as what it is, rather than as a generic parse or method error.

The error

-32020 HeaderMismatch

What causes it

2026-07-28 made `Mcp-Method` required on every request, and `Mcp-Name` required on `tools/call`, `resources/read` and `prompts/get`, so a gateway can route without parsing the body. The moment routing depends on headers, headers that lie become a correctness problem — hence a dedicated error code.

You will see -32020 in four situations: `Mcp-Method` is absent; `MCP-Protocol-Version` is absent; the header protocol version disagrees with `params._meta.protocolVersion`; or `Mcp-Name` is absent, malformed, or disagrees with the name in the body.

If you are RECEIVING it, your client is setting a header inconsistent with what it sends. If your own server should be emitting it and returns `-32601 Method not found` instead, your header validation is running after method dispatch — the checks have to happen first, or an unknown method masks the real problem.

How to fix it

The fix

Validate headers before dispatch, in a fixed orderThe order is load-bearing, because each check assumes the previous one passed. Getting it wrong makes a server report the wrong code for a real condition — reporting -32022 where -32020 is correct, for instance.
The order that produces correct codes
1. Mcp-Method present               -> -32020
2. MCP-Protocol-Version present     -> -32020
3. params._meta present and complete-> -32602
4. header version == _meta version  -> -32020
5. version is supported             -> -32022
6. Mcp-Name rules for this method   -> -32020

The fix

Decode before you compare`Mcp-Name` may arrive Base64-encoded for names that are not header-safe. Comparing the raw header against the body value rejects a perfectly valid request — decode first, then compare.

The fix

Return 400 with the JSON-RPC error, not just a statusA bare 400 with an empty body leaves the client guessing. The response should carry the JSON-RPC error object with code -32020 and a message naming which header disagreed.
A useful -32020
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Mcp-Method header (tools/list) does not match body method (tools/call)"
  }
}

Rules involved

Each of these is checked against a live server, and each links to the exact sentence of the specification it comes from.

RuleWhat we checkLevelIf it fails
MCP-HDR-001Missing Mcp-Method rejected with 400 + HeaderMismatchMUSTfail
MCP-HDR-004Missing MCP-Protocol-Version rejected (modern-only servers)MUSTfail
MCP-HDR-005MCP-Protocol-Version header must match _meta.protocolVersionMUSTfail
MCP-HDR-002Missing Mcp-Name on tools/call rejected with 400 + HeaderMismatchMUSTfail

FAQ

Frequently asked

What is MCP error -32020?

HeaderMismatch, introduced in the 2026-07-28 revision. It means a routing header — Mcp-Method, Mcp-Name or MCP-Protocol-Version — is missing, malformed, or disagrees with the corresponding value in the request body.

Why am I suddenly seeing -32020 after upgrading?

Because 2026-07-28 made Mcp-Method required on every request and Mcp-Name required on tools/call, resources/read and prompts/get. A client that omits them, or sets them from a different source than the body, now gets a specific error where a 2025-era server would have ignored the headers entirely.

What is the difference between -32020 and -32022?

-32020 is a header disagreeing with the body or missing. -32022 is a protocol version that is well-formed and consistent but not supported by this server. A version that is missing from the header is -32020; a version that is present, matches _meta, and is one you do not speak is -32022.

My server returns -32601 instead of -32020. Why?

Your header validation is running after method dispatch. The request reaches the router, the router does not recognise the method, and it answers -32601 Method not found — masking the real problem. Move header validation in front of dispatch.

Check this against your own server

Point the validator at a live MCP server and it reports every rule on this page as pass, warn or fail — each linked to the exact spec sentence it comes from.

Validate a server →