Bad Request: the request headers and body disagree (-32020)

What it means

2026-07-28 copies parts of the JSON-RPC body into HTTP headers so that load balancers and gateways can route without parsing JSON. The specification requires the server to reject a request when a required header is missing or does not match the body, with 400 Bad Request and JSON-RPC code -32020 (HeaderMismatch). We got:

Request	TypeScript SDK v2 (createMcpHandler)	Python SDK 2.3.0
No Mcp-Method header	Bad Request: the request headers and body disagree: the body names method tools/list but the required Mcp-Method header is absent	mcp-method header does not match the request body's method
Mcp-Method: tools/call with a tools/list body	… the body names method tools/list but the Mcp-Method header names tools/call	(same as above)
No MCP-Protocol-Version header	… the body envelope names protocol version 2026-07-28 but the required MCP-Protocol-Version header is absent	Bad Request: Missing session ID (see that entry)

All with HTTP 400 and code -32020, except the last Python case.

A required header is missing

Every 2026-07-28 POST needs:

Header	Value
MCP-Protocol-Version	the version in _meta, for example 2026-07-28
Mcp-Method	the JSON-RPC method, for example tools/call
Mcp-Name	for tools/call and prompts/get the name, for resources/read the uri

Clients built on current SDKs add them. If you write requests by hand, with curl or in a gateway plugin, add all three.

A header does not match the body

Typical causes: a request template where the body was edited but the header was not, a proxy that rewrites headers, or a tool name with non-ASCII characters. The specification says such names go into Mcp-Name Base64-encoded as =?base64?…?=, and the server decodes them before comparing.

Related

• Transports
• Unsupported protocol version