MCP x-mcp-header Validation: Keep Bad Tool Schemas Out of tools/list

The MCP x-mcp-header validation process is often overlooked due to its resemblance to standard JSON Schema metadata annotations. The Streamable HTTP transport serves as a wire contract, allowing clients to copy specific tool arguments into Mcp-Param-* headers, which intermediaries can process, and servers to validate them against the JSON-RPC body. Any issues with the annotation, such as a poor suffix, unsupported type, or unreachable annotation, render the entire tool definition invalid.

The final Streamable HTTP specification replicates request metadata into HTTP headers to avoid the need for JSON-RPC parsing on load balancers, gateways, or WAFs. By appending the x-mcp-header to a tool property, such as {type: object, properties: {region: {type: string, x-mcp-header: Region}}}, a call with region: us-west1 will transmit Mcp-Param-Region: us-west1. The official C# SDK can generate this schema from a parameter attribute, ensuring compatibility with the stable v2 line of tools/list.

MCP x-mcp-header validation rules are stringent, requiring the annotation value to be a non-empty HTTP field-name token, unique irrespective of case, and devoid of control characters, spaces, or separators like a colon. Only string, integer, and boolean properties can be mirrored, while JSON Schema number is excluded. Additionally, integer values must fall within the range of -(2^53 - 1) and 2^53 - 1 for exact representation across conforming implementations.

Reachability is a rule that often catches developers off guard. Annotations can be nested, but the path must solely traverse properties without passing through items, $ref, oneOf, allOf, if, or other composition or conditional keywords. An invalid tool needs to be excluded from the returned tools/list result and logged for diagnostic purposes.

Values adhere to specific encoding rules, with plain ASCII text traveling as-is, while non-ASCII text, control characters, leading or trailing whitespace, and strings resembling the =?base64?...?= sentinel must be encoded in UTF-8/Base64 within that sentinel. Boolean values convert to lowercase true or false, and mathematically integral JSON forms like 42.0 normalize to decimal 42.

To prevent schema drift, a sample draft PR provides a dependency-free .NET 10 executable that scans JSON Schema subschema locations, identifies valid property paths, and flags malformed schemas before any network request. This deterministic verifier encompasses twelve cases, including nested primitive properties, absent and null arguments, non-ASCII and sentinel encoding, case-insensitive duplicates, invalid number types, annotations below items and oneOf, literal example data, invalid HTTP tokens, integral exponent notation, and boundary values for safe integers.

At the server level, recognized Mcp-Param-* values are decoded and compared with the body. A missing, malformed, or mismatched value triggers an HTTP 400 response with JSON-RPC error -32020 (HeaderMismatch). The sample serves as a conformance fixture for testing purposes, emphasizing the importance of transport rules. However, production implementations should rely on current SDKs, validate header/body equality server-side, and maintain authorization checks tied to authenticated principals.