What is the Mcp-Method header in MCP?

The short answer

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call          ← mirrors "method" in the body
Mcp-Name: get_weather           ← mirrors params.name

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "Seattle, WA" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

That last clause — REQUIRED for compliance — is what makes this a migration task rather than an optimisation. A server built against 2025-11-25 does not send or validate these headers at all.

Why the header exists

Everything in MCP's Streamable HTTP transport is a POST to the same URL. Before this revision, an intermediary that wanted to know what a request actually did — to rate-limit tools/call differently from tools/list, to route expensive tools to a bigger pool, to log operations — had to buffer and parse the JSON body. That is expensive, it defeats streaming, and it forces every proxy in the path to understand MCP.

Lifting the method into a header makes the request self-describing at the HTTP layer. An nginx or Envoy config can match on Mcp-Method the way it already matches on any other header, with no body inspection and no MCP awareness.

The three required headers

Mcp-Method arrived alongside two others, and they are easy to confuse because they are all required but not all required on the same requests.

Mismatches, and the -32020 error

The single normative rule that governs all three headers is that they must agree with the body:

POST /mcp
Mcp-Method: tools/list        ← says list
{ "method": "tools/call", … } ← does call

// A server that dispatches on the body and ignores
// the header will happily run tools/call here.
// Every gateway in the path believed it was a list.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Method does not match body method"
  }
}

-32020 sits in the -32020–-32099 range the specification reserves for itself, added in this revision. It is one of three new codes, next to -32021 MissingRequiredClientCapability and -32022 UnsupportedProtocolVersion.

Case-insensitivity is normative, not incidental

This one bites in production rather than in testing, because every client in your test suite probably sends the documented casing. The failure appears when a different client, an HTTP/2 stack that lowercases field names, or a proxy that normalises them, sends mcp-method and your exact-match lookup returns undefined — which your code then treats as a missing required header.

// Wrong: works only for one casing
const method = req.headers["Mcp-Method"]

// Right: Node lowercases incoming header names for you,
// but be explicit rather than relying on the runtime
const method = req.headers["mcp-method"]

// In a framework that hands you a raw Headers object:
const method = headers.get("mcp-method")   // Headers.get is case-insensitive

The Base64 sentinel encoding

HTTP header values are constrained to a narrow ASCII set, but tool and prompt names are not. The spec resolves that with a sentinel encoding — a name outside the safe set travels Base64-encoded — and puts the decoding obligation on the server:

The failure mode is quiet and complete: a server that compares the raw header against the body name will reject every request for a tool whose name needs encoding, while every ASCII-named tool keeps working. It looks like “that one tool is broken” rather than a header bug.

Mcp-Param-{Name}, for servers that opt in

A tool can promote individual input parameters into headers by marking them x-mcp-header in its inputSchema. That is opt-in — most servers never do it — but a server that declares it takes on two extra obligations:

Both rules are marked v1: false in our catalogue, meaning we do not yet probe them automatically; they need a server that declares x-mcp-header in a published schema before there is anything to check. The schema-side constraints on those declarations are covered by the seven MCP-SCH-* rules.

The 10 header rules we check

Frequently asked

Related