Validate Mcp-Param-* headers server-side on the 2026-07-28 HTTP path (SEP-2243)

Servers that process the request body MUST validate that Mcp-Param-*
headers match the corresponding x-mcp-header-annotated body arguments,
rejecting mismatches with HTTP 400 and -32020 (HeaderMismatch). The
client half shipped earlier; this adds the server half:

- mcp.shared.inbound grows a pure, exported validate_mcp_param_headers
  built on the same walker and scalar rendering the client emit side
  uses, so the two halves of the mirror contract cannot drift. Presence
  rules follow the spec's scenario table; recognized headers supplied
  more than once are rejected (first-wins consumers vs last-wins
  validation would otherwise disagree); integer values compare
  numerically behind a canonical-decimal gate, exactly and in both
  directions; unrecognized headers stay ignored.
- decode_header_value now requires canonical base64 in the sentinel
  (bad padding, stray characters, non-zero trailing bits, or invalid
  UTF-8 are malformed), which the conformance suite mandates for
  Mcp-Param-* and which now applies to Mcp-Name symmetrically.
- The modern HTTP entry validates tools/call pre-dispatch, resolving
  the called tool's inputSchema through the server's own registered
  tools/list handler via the normal serve_one path with the caller's
  envelope - so a visibility-scoped catalog validates exactly what
  this caller was advertised, with nothing to configure on MCPServer
  or lowlevel servers. The listing is skipped (never failing the
  call) when no tools/list handler is registered, the tool is not
  advertised, the handler raises (logged), pagination exceeds a page
  cap or cycles, or the call has no arguments and no Mcp-Param-*
  headers.
- Remove http-custom-header-server-validation from both conformance
  expected-failures baselines; the scenario passes 9/9 against the
  everything-server, with http-header-validation and server-stateless
  unchanged.

Author: maxisbey

.github/actions/conformance/expected-failures.2026-07-28.yml

@@ -26,6 +26,3 @@ server:
   # SEP-2575 subscriptions/listen is not implemented yet; see the matching
   # entry in expected-failures.yml for the full rationale.
   - server-stateless
-  # SEP-2243 Mcp-Param-* server-side validation is not implemented yet; see
-  # the matching entry in expected-failures.yml for the full rationale.
-  - http-custom-header-server-validation

.github/actions/conformance/expected-failures.yml

@@ -23,13 +23,6 @@ server:
   # failures in the scenario's other 25 (currently passing) checks — the
   # baseline is per-scenario, not per-check.
   - server-stateless
-  # SEP-2243 Mcp-Param-* server-side validation is not implemented yet. The
-  # everything-server's `test_x_mcp_header` tool arms these checks (without an
-  # x-mcp-header-annotated tool the harness skips all of them silently); the
-  # accept-path checks pass, the reject-path checks fail until the server
-  # validates Mcp-Param headers against body params. Read by the draft leg and
-  # the bare `--suite all` leg; the 2026-07-28 leg carries its own entry.
-  - http-custom-header-server-validation
   # SEP-2663 (io.modelcontextprotocol/tasks): the SDK does not implement the
   # tasks extension yet. These extension-tagged scenarios are selected only by
   # the bare `--suite all` leg — extension scenarios never match a

docs/migration.md

@@ -427,6 +427,14 @@ On `ClientSession`, `call_tool` / `get_prompt` / `read_resource` still return th
 
 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.
 
+### 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.
+
+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.
+
 ### `Client` verbs may serve cached responses ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549))
 
 On protocol 2026-07-28, servers attach caching hints (`ttlMs`, `cacheScope`) to the cacheable results, and `Client` now honors them: `list_tools`, `list_prompts`, `list_resources`, `list_resource_templates`, and `read_resource` may serve a cached response instead of making a round trip, for as long as the server's `ttlMs` says the result is fresh. With the default configuration, servers that send no hints, including every pre-2026 server, see identical call-for-call behavior, because hint-less results are not cached (a `CacheConfig.default_ttl_ms` above zero caches them too). Pass `Client(..., cache=False)` to disable the cache and restore v1 behavior exactly; per-call control (`cache_mode`) and configuration (`CacheConfig`) are described in [Caching hints](advanced/caching.md).

src/mcp/server/_streamable_http_modern.py

@@ -22,14 +22,17 @@
 import logging
 from collections.abc import Awaitable, Mapping
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Final, TypeVar
+from typing import TYPE_CHECKING, Any, Final, TypeVar, cast
 
 import anyio
 from anyio.streams.memory import MemoryObjectSendStream
 from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
     INTERNAL_ERROR,
     INVALID_REQUEST,
     PARSE_ERROR,
+    PROTOCOL_VERSION_META_KEY,
     ClientCapabilities,
     ErrorData,
     Implementation,
@@ -53,8 +56,11 @@
 from mcp.shared.exceptions import NoBackChannelError
 from mcp.shared.inbound import (
     ERROR_CODE_HTTP_STATUS,
+    MCP_PARAM_HEADER_PREFIX,
     InboundLadderRejection,
+    InboundModernRoute,
     classify_inbound_request,
+    validate_mcp_param_headers,
 )
 from mcp.shared.jsonrpc_dispatcher import handler_exception_to_error_data, progress_token_from_params
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata
@@ -172,6 +178,22 @@ def _sse_event(msg: JSONRPCResponse | JSONRPCError | JSONRPCNotification) -> byt
     return f"event: message\r\ndata: {data}\r\n\r\n".encode()
 
 
+async def _write_rejection(
+    rejection: InboundLadderRejection,
+    request_id: RequestId,
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+) -> None:
+    """Send a ladder rejection as its JSON-RPC error with the table-mapped HTTP status."""
+    rej = JSONRPCError(
+        jsonrpc="2.0",
+        id=request_id,
+        error=ErrorData(code=rejection.code, message=rejection.message, data=rejection.data),
+    )
+    await _write(rej, scope, receive, send)
+
+
 async def _write(
     msg: JSONRPCResponse | JSONRPCError,
     scope: Scope,
@@ -192,6 +214,123 @@ async def _write(
     )(scope, receive, send)
 
 
+_MCP_PARAM_PREFIX_LOWER: Final = MCP_PARAM_HEADER_PREFIX.lower()
+
+_MCP_PARAM_LIST_PAGE_CAP: Final = 100
+"""Upper bound on `tools/list` pages walked while resolving a tool schema for
+`Mcp-Param-*` validation. A paginator bug (non-terminating or cycling cursor
+chain) must degrade to a logged validation skip, never a request-path hang."""
+
+
+async def _tool_input_schema(
+    app: Server[Any],
+    request: Request,
+    request_id: RequestId,
+    verdict: InboundModernRoute,
+    lifespan_state: Any,
+    name: str,
+) -> Any | None:
+    """Resolve `name`'s inputSchema from the server's own registered `tools/list` handler.
+
+    The synthetic listing runs through the normal `serve_one` path — the
+    caller's envelope (rebuilt from the classifier verdict, so caller-side
+    `_meta` extras like a progress token are not replayed), the middleware
+    chain, a fresh per-page `Connection`, and an absorbing dispatch context
+    (no SSE sink, so request-scoped notifications drop instead of raising) —
+    so a visibility-scoped catalog yields exactly what *this* caller was
+    advertised. Returns `None` (caller skips validation) when the listing
+    raises, paginates past the cap or cycles, or never advertises the tool.
+    """
+    meta = {
+        PROTOCOL_VERSION_META_KEY: verdict.protocol_version,
+        CLIENT_INFO_META_KEY: verdict.client_info,
+        CLIENT_CAPABILITIES_META_KEY: verdict.client_capabilities,
+    }
+    list_params: dict[str, Any] = {"_meta": meta}
+    seen_cursors: set[str] = set()
+    client_info = _typed(Implementation, verdict.client_info)
+    client_capabilities = _typed(ClientCapabilities, verdict.client_capabilities)
+    dctx = _SingleExchangeDispatchContext(
+        transport=TransportContext(kind="streamable-http", can_send_request=False, headers=request.headers),
+        request_id=request_id,
+        message_metadata=ServerMessageMetadata(request_context=request),
+    )
+    for _ in range(_MCP_PARAM_LIST_PAGE_CAP):
+        # A fresh per-page Connection is load-bearing: serve_one tears down
+        # the connection's exit stack on the way out. The dispatch context is
+        # page-independent and reused.
+        connection = Connection.from_envelope(verdict.protocol_version, client_info, client_capabilities)
+        try:
+            result = await serve_one(
+                app, dctx, "tools/list", list_params, connection=connection, lifespan_state=lifespan_state
+            )
+        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")
+            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 —
+            # dispatch owns rejecting a genuinely unknown tool.
+            return None
+        if cursor in seen_cursors:
+            logger.warning("Mcp-Param header validation skipped: the tools/list handler returned a cursor cycle")
+            return None
+        seen_cursors.add(cursor)
+        list_params = {"_meta": meta, "cursor": cursor}
+    logger.warning(
+        "Mcp-Param header validation skipped: tools/list pagination did not terminate within %d pages",
+        _MCP_PARAM_LIST_PAGE_CAP,
+    )
+    return None
+
+
+async def _mcp_param_rejection(
+    app: Server[Any],
+    request: Request,
+    req: JSONRPCRequest,
+    verdict: InboundModernRoute,
+    lifespan_state: Any,
+) -> InboundLadderRejection | None:
+    """Validate a `tools/call` request's `Mcp-Param-*` headers against the called tool's schema.
+
+    Runs post-classification, pre-dispatch — and before any SSE machinery, so
+    a rejection is always a plain `application/json` 400 (the spec's MUST for
+    header-validation failures). The schema source is the registered
+    `tools/list` handler; with none registered the catalog is undiscoverable,
+    no client can have been told about an `x-mcp-header` annotation, and there
+    is no recognized header to validate. A mis-shaped `name`/`arguments` is
+    left to params validation at dispatch.
+    """
+    if req.method != "tools/call" or app.get_request_handler("tools/list") is None:
+        return None
+    params = req.params or {}
+    name = params.get("name")
+    if not isinstance(name, str):
+        return None
+    raw_arguments = params.get("arguments")
+    if raw_arguments is not None and not isinstance(raw_arguments, Mapping):
+        return None
+    arguments: Mapping[str, Any] = cast("Mapping[str, Any]", raw_arguments) if raw_arguments is not None else {}
+    # ASGI guarantees lowercase header names, same invariant the classifier
+    # leans on; the pure validator re-folds for arbitrary carriers.
+    if not arguments and not any(header.startswith(_MCP_PARAM_PREFIX_LOWER) for header in request.headers):
+        # With no argument values and no `Mcp-Param-*` headers, no declaration
+        # could be violated in either direction — skip the listing outright.
+        return None
+    input_schema = await _tool_input_schema(app, request, req.id, verdict, lifespan_state, name)
+    if input_schema is None:
+        return None
+    return validate_mcp_param_headers(input_schema, arguments, request.headers)
+
+
 async def handle_modern_request(
     app: Server[Any],
     security_settings: TransportSecuritySettings | None,
@@ -254,10 +393,12 @@ async def handle_modern_request(
 
     verdict = classify_inbound_request(decoded, headers=dict(request.headers))
     if isinstance(verdict, InboundLadderRejection):
-        rej = JSONRPCError(
-            jsonrpc="2.0", id=req.id, error=ErrorData(code=verdict.code, message=verdict.message, data=verdict.data)
-        )
-        await _write(rej, scope, receive, send)
+        await _write_rejection(verdict, req.id, scope, receive, send)
+        return
+
+    mcp_param_rejection = await _mcp_param_rejection(app, request, req, verdict, lifespan_state)
+    if mcp_param_rejection is not None:
+        await _write_rejection(mcp_param_rejection, req.id, scope, receive, send)
         return
 
     connection = Connection.from_envelope(