Harden Mcp-Param validation per review: rendering as one fact, duplicate routing headers, parse-limit 500s

- A value's header rendering (or its absence) is now a single shared fact
  (_render_header_scalar returns None for non-primitives and integers
  beyond the int-to-str digit limit): the client omits such headers, the
  validator treats a header claiming such a value as a mismatch, and a
  huge-integer body can no longer raise out of the public validator.
- A non-canonical-decimal header for an integer declaration falls back to
  the rendered comparison instead of rejecting outright, so the client's
  own scientific-notation rendering of large integral floats (str(1e16)
  == '1e+16') round-trips against this server.
- Duplicated MCP-Protocol-Version / Mcp-Method / Mcp-Name raw header
  lines are rejected before classification (find_duplicated_routing_header)
  - the same first-wins/last-wins divergence the Mcp-Param duplicate
  rejection closes, where it matters most.
- The synthetic listing's fail-open boundary now covers the result scan
  (a middleware short-circuiting tools/list with a mis-shaped result is a
  logged skip, not a 500), and a mis-shaped envelope failing the listing's
  surface validation logs at debug as client fault instead of an
  error-level traceback blaming the tools/list handler.
- json.loads failures are caught as ValueError (an integer literal beyond
  the digit limit raises the bare parent, not JSONDecodeError), keeping
  unparseable bodies at 400 + PARSE_ERROR.
- migration.md: handler-raise skip is logged as an error, not a warning;
  document the omitted-unrenderable-value and duplicate-line rules.

Author: maxisbey

docs/migration.md

@@ -425,13 +425,13 @@ On `ClientSession`, `call_tool` / `get_prompt` / `read_resource` still return th
 
 ### `call_tool` mirrors `x-mcp-header` arguments into `Mcp-Param-*` headers ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243))
 
-For protocol 2026-07-28 over Streamable HTTP, a tool's input-schema property may carry an `x-mcp-header` annotation. When a tool the client has listed is called, each annotated argument is mirrored into an `Mcp-Param-<name>` request header (string verbatim, integer as decimal, boolean as `true`/`false`, base64-sentinel-wrapped when not header-safe; `null`/absent arguments are omitted). The argument is also left in the request body. `list_tools` caches a tool's annotations, so list a tool before calling it to enable mirroring; a tool the client never listed emits no `Mcp-Param-*` headers. Other transports ignore the annotation.
+For protocol 2026-07-28 over Streamable HTTP, a tool's input-schema property may carry an `x-mcp-header` annotation. When a tool the client has listed is called, each annotated argument is mirrored into an `Mcp-Param-<name>` request header (string verbatim, integer as decimal, boolean as `true`/`false`, base64-sentinel-wrapped when not header-safe; `null`/absent arguments — and values with no scalar rendering, such as objects or arrays — are omitted). The argument is also left in the request body. `list_tools` caches a tool's annotations, so list a tool before calling it to enable mirroring; a tool the client never listed emits no `Mcp-Param-*` headers. Other transports ignore the annotation.
 
 ### Servers validate `Mcp-Param-*` headers against the request body ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243))
 
 The server half of the same contract: on the 2026-07-28 Streamable HTTP path, a `tools/call` whose tool declares `x-mcp-header` annotations is validated before dispatch — each annotated argument and its mirroring `Mcp-Param-*` header must be present together and agree (after base64-sentinel decoding; integers compare numerically), or absent together. A violation is rejected with HTTP 400 and JSON-RPC error `-32020` (`HeaderMismatch`), as the spec requires. A client that sends an annotated argument *without* its header — for example one that never listed the tool — is therefore rejected instead of silently served; the spec's recovery is to re-list and retry.
 
-There is nothing to configure. The server resolves the called tool's schema through its own registered `tools/list` handler (for `MCPServer`, the built-in one), so the validated catalog is exactly what that caller would be shown. Two consequences worth knowing: the listing runs internally on validated calls, so middleware and an expensive or paginated `tools/list` handler see extra invocations; and validation is skipped — never failing the call — when no `tools/list` handler is registered, the tool isn't in the listing, the handler raises (logged as a warning), or the call has no arguments and no `Mcp-Param-*` headers. Headers with no matching annotation are ignored; a recognized header supplied more than once is rejected. The codec and validator are public in `mcp.shared.inbound` (`decode_header_value`, `validate_mcp_param_headers`) for low-level servers hosting their own HTTP entry.
+There is nothing to configure. The server resolves the called tool's schema through its own registered `tools/list` handler (for `MCPServer`, the built-in one), so the validated catalog is exactly what that caller would be shown. Two consequences worth knowing: the listing runs internally on validated calls, so middleware and an expensive or paginated `tools/list` handler see extra invocations; and validation is skipped — never failing the call — when no `tools/list` handler is registered, the tool isn't in the listing, the handler raises (logged as an error), or the call has no arguments and no `Mcp-Param-*` headers. Headers with no matching annotation are ignored; a recognized header supplied more than once is rejected, as is a duplicated `MCP-Protocol-Version`, `Mcp-Method`, or `Mcp-Name` line. The codec and validator are public in `mcp.shared.inbound` (`decode_header_value`, `validate_mcp_param_headers`) for low-level servers hosting their own HTTP entry.
 
 Base64-sentinel decoding is strict everywhere it applies, including the `Mcp-Name` header: a `=?base64?...?=` value whose payload is not canonical base64 (wrong padding, stray characters, non-zero trailing bits) or not valid UTF-8 is rejected as malformed rather than leniently decoded.
 

src/mcp/server/_streamable_http_modern.py

@@ -29,6 +29,7 @@
 from mcp_types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
+    HEADER_MISMATCH,
     INTERNAL_ERROR,
     INVALID_REQUEST,
     PARSE_ERROR,
@@ -60,6 +61,7 @@
     InboundLadderRejection,
     InboundModernRoute,
     classify_inbound_request,
+    find_duplicated_routing_header,
     validate_mcp_param_headers,
 )
 from mcp.shared.jsonrpc_dispatcher import handler_exception_to_error_data, progress_token_from_params
@@ -264,17 +266,27 @@ async def _tool_input_schema(
             result = await serve_one(
                 app, dctx, "tools/list", list_params, connection=connection, lifespan_state=lifespan_state
             )
+            for tool in result.get("tools", []):
+                if tool.get("name") == name:
+                    return tool.get("inputSchema")
+            cursor = result.get("nextCursor")
+        except ValidationError:
+            # Client fault: a mis-shaped envelope value the classifier admits
+            # on key presence alone fails the kernel's surface validation here
+            # first. The real dispatch produces the INVALID_PARAMS reply, so
+            # this is not worth more than a debug line (an exception-level log
+            # would let any client flood the log blaming the server).
+            logger.debug("Mcp-Param header validation skipped: the request envelope fails tools/list validation")
+            return None
         except Exception:
             # Boundary by design: header validation must never break a working
-            # call path, so a raising listing skips validation for this request
-            # — loudly, because the skip is fail-open. (A server broken here is
-            # broken for real discovery too.)
-            logger.exception("Mcp-Param header validation skipped: the tools/list handler raised")
+            # call path, so a failing listing — the handler raising, or a
+            # middleware short-circuit returning a mis-shaped result — skips
+            # validation for this request. Loudly, because the skip is
+            # fail-open. (A server broken here is broken for real discovery
+            # too.)
+            logger.exception("Mcp-Param header validation skipped: the tools/list listing failed")
             return None
-        for tool in result.get("tools", []):
-            if tool.get("name") == name:
-                return tool.get("inputSchema")
-        cursor = result.get("nextCursor")
         if not isinstance(cursor, str):
             # Listing exhausted without advertising `name`: nothing was
             # declared to this caller, so there is nothing to validate —
@@ -369,7 +381,10 @@ async def handle_modern_request(
     body = await request.body()
     try:
         decoded = json.loads(body)
-    except json.JSONDecodeError:
+    except ValueError:
+        # ValueError, not its JSONDecodeError subclass: an integer literal
+        # beyond CPython's int-conversion digit limit raises the bare parent
+        # and is just as unparseable.
         rej = JSONRPCError(jsonrpc="2.0", id=None, error=ErrorData(code=PARSE_ERROR, message="Parse error"))
         await _write(rej, scope, receive, send)
         return
@@ -391,6 +406,16 @@ async def handle_modern_request(
         await _write(rej, scope, receive, send)
         return
 
+    duplicated = find_duplicated_routing_header(request.headers.items())
+    if duplicated is not None:
+        # The classifier receives a folded mapping that can no longer show
+        # duplicates, so the raw-carrier check lives here: a routing header
+        # supplied twice is unverifiable (a consumer reading one copy and the
+        # validator the other would disagree).
+        rejection = InboundLadderRejection(code=HEADER_MISMATCH, message=f"{duplicated} header appears more than once")
+        await _write_rejection(rejection, req.id, scope, receive, send)
+        return
+
     verdict = classify_inbound_request(decoded, headers=dict(request.headers))
     if isinstance(verdict, InboundLadderRejection):
         await _write_rejection(verdict, req.id, scope, receive, send)

src/mcp/shared/inbound.py

@@ -14,7 +14,7 @@
 import base64
 import binascii
 import re
-from collections.abc import Iterator, Mapping, Sequence
+from collections.abc import Iterable, Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from types import MappingProxyType
 from typing import Any, Final, cast
@@ -49,6 +49,7 @@
     "classify_inbound_request",
     "decode_header_value",
     "encode_header_value",
+    "find_duplicated_routing_header",
     "find_invalid_x_mcp_header",
     "mcp_param_headers",
     "validate_mcp_param_headers",
@@ -260,14 +261,26 @@ def _annotated_positions(input_schema: Any) -> Iterator[tuple[tuple[str, ...], s
             yield path, token, schema
 
 
-def _render_header_scalar(value: Any) -> str:
-    """Render an argument value the way the client mirrors it into a header.
+def _render_header_scalar(value: Any) -> str | None:
+    """Render an argument value the way the client mirrors it into a header, or `None`
+    when no header rendering exists.
 
-    Shared by emit (:func:`mcp_param_headers`) and validate
-    (:func:`validate_mcp_param_headers`) so the comparison is the exact
-    inverse of the rendering by construction.
+    The single source of the "mirrorable value" fact, shared by emit
+    (:func:`mcp_param_headers`, which omits the header) and validate
+    (:func:`validate_mcp_param_headers`, for which a header claiming an
+    unmirrorable value can never match) so the two sides agree by
+    construction. Unmirrorable: non-primitive values — the spec defines
+    rendering for string/integer/boolean only — and integers beyond CPython's
+    int-to-str conversion limit, which no JSON peer can express anyway.
     """
-    return ("true" if value else "false") if isinstance(value, bool) else str(value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if not isinstance(value, str | int | float):
+        return None
+    try:
+        return str(value)
+    except ValueError:
+        return None
 
 
 def mcp_param_headers(header_map: Mapping[tuple[str, ...], str], arguments: Mapping[str, Any]) -> dict[str, str]:
@@ -278,14 +291,15 @@ def mcp_param_headers(header_map: Mapping[tuple[str, ...], str], arguments: Mapp
     `Mcp-Param-<token>` carrying it: `bool` as `true`/`false`, other scalars via
     `str`, each passed through :func:`encode_header_value` so a non-token value
     is base64-wrapped. A path that hits a missing key or a non-mapping node is
-    skipped, matching the spec's "omit the header when no value is present".
+    skipped, matching the spec's "omit the header when no value is present" —
+    as is a value with no header rendering (see :func:`_render_header_scalar`).
     """
     headers: dict[str, str] = {}
     for path, token in header_map.items():
         value = _value_at_path(arguments, path)
-        if value is None:
+        if value is None or (rendered := _render_header_scalar(value)) is None:
             continue
-        headers[f"{MCP_PARAM_HEADER_PREFIX}{token}"] = encode_header_value(_render_header_scalar(value))
+        headers[f"{MCP_PARAM_HEADER_PREFIX}{token}"] = encode_header_value(rendered)
     return headers
 
 
@@ -343,6 +357,33 @@ class InboundLadderRejection:
     data: Any = None
 
 
+_ROUTING_HEADER_NAMES: Final = frozenset({MCP_PROTOCOL_VERSION_HEADER, MCP_METHOD_HEADER, MCP_NAME_HEADER})
+
+
+def find_duplicated_routing_header(headers: Iterable[tuple[str, str]]) -> str | None:
+    """Name of a routing header supplied more than once in raw header lines, or `None`.
+
+    `headers` is the carrier's raw `(name, value)` pairs (e.g.
+    `request.headers.items()`), which — unlike a folded mapping — still shows
+    duplicates. The routing headers (`MCP-Protocol-Version`, `Mcp-Method`,
+    `Mcp-Name`) are always recognized, so a duplicate is always unverifiable:
+    a consumer reading one copy and a validator reading the other would
+    disagree, the divergence header validation exists to prevent. Callers
+    reject with `HEADER_MISMATCH` before running the validation ladder.
+    `Mcp-Param-*` duplicates are not this function's job:
+    :func:`validate_mcp_param_headers` rejects recognized ones and the spec's
+    forward-and-ignore rule covers unrecognized ones.
+    """
+    seen: set[str] = set()
+    for name, _ in headers:
+        key = name.lower()
+        if key in _ROUTING_HEADER_NAMES:
+            if key in seen:
+                return key
+            seen.add(key)
+    return None
+
+
 def classify_inbound_request(
     body: Mapping[str, Any],
     *,
@@ -434,31 +475,35 @@ def classify_inbound_request(
 _CANONICAL_DECIMAL = re.compile(r"^-?[0-9]+(\.[0-9]+)?$")
 
 
-def _mcp_param_value_matches(prop_type: Any, value: Any, decoded: str) -> bool:
+def _mcp_param_value_matches(prop_type: Any, value: Any, rendered: str, decoded: str) -> bool:
     """True when a decoded `Mcp-Param-*` header value agrees with the body argument.
 
-    The exact inverse of :func:`_render_header_scalar`: booleans compare
-    against `true`/`false`; an integer-typed declaration with an integral body
-    value (`int`, or a `float` like `42.0` that JSON Schema also admits as an
-    integer) compares numerically (`42` matches `42.0`, the spec's SHOULD) but
-    only for canonical-decimal headers, and exactly — no float round-trip, so
-    values outside the IEEE754 safe range still compare correctly. A header
-    whose integer part overflows CPython's int-conversion digit limit can
-    never name a JSON-expressible value, so it simply does not match.
+    `rendered` is the argument's own header rendering, so the fallback
+    comparison is the exact inverse of the emit side by construction. An
+    integer-typed declaration with an integral body value (`int`, or a `float`
+    like `42.0` that JSON Schema also admits as an integer; `bool` excluded —
+    it renders `true`/`false`) compares numerically (`42` matches `42.0`, the
+    spec's SHOULD) but only for canonical-decimal headers, and exactly — no
+    float round-trip, so values outside the IEEE754 safe range still compare
+    correctly. A non-canonical header (e.g. scientific notation) falls back to
+    the rendered comparison, so the client's own rendering of any value always
+    matches; a header whose integer part overflows CPython's int-conversion
+    digit limit can never name a JSON-expressible value, so it does not match.
     """
-    if isinstance(value, bool):
-        return decoded == _render_header_scalar(value)
-    if prop_type == "integer" and (isinstance(value, int) or (isinstance(value, float) and value.is_integer())):
-        if _CANONICAL_DECIMAL.fullmatch(decoded) is None:
-            return False
+    if (
+        prop_type == "integer"
+        and not isinstance(value, bool)
+        and (isinstance(value, int) or (isinstance(value, float) and value.is_integer()))
+        and _CANONICAL_DECIMAL.fullmatch(decoded) is not None
+    ):
         whole, _, fraction = decoded.partition(".")
         if fraction and set(fraction) != {"0"}:
             return False
         try:
             return int(whole) == int(value)
         except ValueError:
             return False
-    return decoded == _render_header_scalar(value)
+    return decoded == rendered
 
 
 def validate_mcp_param_headers(
@@ -519,7 +564,10 @@ def validate_mcp_param_headers(
                     message=f"{header_name} header is present but the request body's {argument!r} argument is absent",
                 )
             continue
-        if not isinstance(value, str | int | float):
+        rendered = _render_header_scalar(value)
+        if rendered is None:
+            # No header rendering exists for this value, so a conforming
+            # client omitted the header; one claiming it can never match.
             if raw is not None:
                 return InboundLadderRejection(
                     code=HEADER_MISMATCH,
@@ -537,7 +585,7 @@ def validate_mcp_param_headers(
                 code=HEADER_MISMATCH,
                 message=f"{header_name} header carries a malformed base64 sentinel value",
             )
-        if not _mcp_param_value_matches(schema.get("type"), value, decoded):
+        if not _mcp_param_value_matches(schema.get("type"), value, rendered, decoded):
             return InboundLadderRejection(
                 code=HEADER_MISMATCH,
                 message=f"{header_name} header does not match the request body's {argument!r} argument",