CSE Roadmap

Core tier · about 6 hours · 14 parts

Part 3 of 14 · 3 min read

Probing an unknown server, and the headers that mirror the body

Think of knocking before you walk into a room you have never been in: you learn something from the answer, or the silence, before you commit to a plan.

In plain words: a client that must work with servers it did not choose probes first and falls back on silence or an unrecognised error, never on one specific error code. Once connected over Streamable HTTP, some header fields are copied from the message body so intermediaries can route without parsing JSON. That only works safely if the server checks that the header and the body still agree.

A worked example. On stdio, the example's legacy server stays silent until it is sent a plain initialize, with no reply at all to the modern probe server/discover. The client waits out its timeout, falls back to initialize, and the whole connect takes about 0.5 s instead of the roughly 0.04 s a modern server answers in. Over HTTP, the example builds a small gateway that allows only the tool search, deciding entirely from the Mcp-Name header. An honest call to place_hold is correctly blocked with HTTP 403. An attacker then sends a request with the header Mcp-Name: search but a body that actually calls place_hold. Against a server that never compares the header with the body, this spoofed request gets HTTP 200 and creates 1 hold. Against a server that validates them against each other, it gets HTTP 400 with JSON-RPC error -32020 and creates 0 holds.

The key lines. From code/mini-transport/headers.py:

# from code/mini-transport/headers.py
def validate(headers: dict[str, str], msg: dict, schema: dict | None = None) -> str | None:
    """Server side: return a reason string if headers and body disagree, else None."""
    low = {k.lower(): v for k, v in headers.items()}
    p = msg.get("params") or {}
    want_version = (p.get("_meta") or {}).get(rpc.META_VERSION)
    if "mcp-protocol-version" not in low:
        return "missing MCP-Protocol-Version header"
    if low["mcp-protocol-version"] != want_version:
        return f"MCP-Protocol-Version header {low['mcp-protocol-version']!r} does not match body {want_version!r}"

Read it as: the function compares each mirrored header against the exact same field in the body it was supposedly copied from. It returns a reason the moment any pair disagrees. That comparison is the entire fix for the spoofing attack above. A gateway deciding from a header is only as trustworthy as the guarantee that nothing downstream can act on a different value.

Mirrored header, HeaderMismatch

A mirrored header is a value copied from a JSON-RPC message's body into an HTTP header, such as Mcp-Method or Mcp-Name, so intermediaries can route without parsing the body. HeaderMismatch (-32020) is the error a server must return when a header and the body field it claims to mirror disagree.

Example: "a control is only as good as the information it decides from" is the same lesson module 1 teaches about a gateway's checks. Here the gateway itself was correct, but the server behind it made the gateway's decision bypassable by never checking that the header told the truth.