What headers must an MCP Streamable HTTP POST carry, and what is HeaderMismatchError?

## The three required headers MCP's Streamable HTTP transport in revision 2026-07-28 puts a small, fixed amount of information into HTTP headers that also appears in the JSON-RPC body. **`MCP-Protocol-Version`** — the revision string, e.g. `2026-07-28`. The same value is required inside the request body at `params._meta` under the key `io.modelcontextprotocol/protocolVersion`. The header and the `_meta` value MUST be identical. **`Mcp-Method`** — mirrors the JSON-RPC `method` of the body: `tools/call`, `resources/read`, `tools/list`, `server/discover`, and so on. **`Mcp-Name`** — the name of the thing being addressed. It is required for the three calls that name a target: `tools/call` (the tool name), `resources/read` (the resource), and `prompts/get` (the prompt). Other methods do not address a named entity and do not carry it. ## The mismatch error If `MCP-Protocol-Version` and the `_meta` protocol version differ, the server returns HTTP `400` and a JSON-RPC error object with code **`-32020`**, named **`HeaderMismatchError`**. This code sits inside the block `-32020` to `-32099`, which the MCP specification reserves for itself on top of the JSON-RPC standard codes. Note what this error is *not*. It is not "I do not speak that version" — that is `-32022`, `UnsupportedProtocolVersionError`, which carries `data.supported` and `data.requested`. `-32020` says something narrower and more damning: the request contradicts itself. The client sent two statements about which protocol revision this is, and they disagree, so the server refuses to guess which one to believe. ## Why duplicate information into headers at all The headers exist for everything sitting between the client and the MCP server. - **Routing.** A gateway can send `tools/call` to one pool and cheap metadata calls like `tools/list` to another, or route by `Mcp-Name` so that one expensive tool runs on dedicated capacity. - **Policy.** A WAF or authorization proxy can allow `resources/read` but require step-up authentication for a named destructive tool, without implementing a JSON-RPC parser. - **Observability.** Access logs, traces and metrics get a meaningful dimension for free. Without the headers, every request in the log is an indistinguishable `POST /mcp`, which makes latency and error-rate analysis per tool impossible. - **Rate limiting and quotas.** Per-method and per-tool limits become an edge concern rather than an application concern. - **Cost.** Body inspection at the edge means buffering and parsing every request, which is both slow and a denial-of-service surface of its own. ## Why the mismatch has to be fatal Duplicated data invites drift, and drift between an edge decision and a server action is a security problem, not a hygiene problem. If the header said one revision and the body another, a version-aware policy at the edge would be evaluating a different request from the one the server executes. The specification removes the ambiguity by making disagreement an error, and by making it an error the *server* raises — the party that can see both values. The same reasoning explains why `Mcp-Method` and `Mcp-Name` are worth taking seriously in a server implementation even though the body is authoritative: a server that ignores them entirely will happily execute requests whose headers lied to the gateway. A defensive server validates that they agree with the body and rejects the request when they do not. ## Implementation notes - Generate the headers from the same structure that produced the body. Hand-writing them twice in client code is how mismatches happen. - Do not try to be helpful by "correcting" a mismatch on the server. Returning `400` with `-32020` gives the client an unambiguous, debuggable signal; silently preferring one value hides a client bug that will resurface as inconsistent behaviour under a gateway. - Header names are case-insensitive in HTTP, but the values are not: the protocol version is an exact `YYYY-MM-DD` string, and tool names are case-sensitive. - These headers are per request, like everything else in this revision. There is no handshake that establishes them once for a connection, and a server MUST NOT infer them from an earlier request that arrived on the same connection. ## What an interviewer is checking The surface answer is "three headers". The answer that lands explains the *why*: MCP is stateless, one endpoint and one verb, so without these headers every request is opaque to infrastructure — and once you duplicate data, you must define what happens when the copies disagree.