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

MCP x-mcp-header validation is easy to miss because the annotation looks like ordinary JSON Schema metadata. On the 2026-07-28 Streamable HTTP transport, it is a wire contract: the client copies selected tool arguments into Mcp-Param-* headers, intermediaries can act on those headers, and the server checks them against the JSON-RPC body. I treat that contract as something to test before a tool reaches tools/list . A bad suffix, an unsupported type, or an unreachable annotation makes the whole tool definition invalid. Silently accepting it only moves the failure to a harder place to diagnose. Why the same value travels twice The final Streamable HTTP specification mirrors request metadata into HTTP headers so a load balancer, gateway, or WAF does not need to parse JSON-RPC. A server can add x-mcp-header to a tool property: { "type" : "object" , "properties" : { "region" : { "type" : "string" , "x-mcp-header" : "Region" } } } A call with "region": "us-west1" then carries: Mcp-Param-Region: us-west1 The official C# SDK can generate that schema from a parameter attribute: [ McpServerTool ] public static string ExecuteSql ( [ McpHeader ( "Region" )] string region , string query ) => $"Queued for { region } " ; Current C# SDK v2 tool documentation describes both schema generation and automatic header projection. The feature is on the stable v2 line; it is not necessary to pin an earlier preview or release candidate. MCP x-mcp-header validation rules The final tool definition rules are deliberately narrow. The annotation value must be a non-empty HTTP field-name token and must be unique without regard to case. Region and region therefore collide. Control characters, spaces, and separators such as a colon are not valid suffix characters. Only string , integer , and boolean properties can be mirrored. JSON Schema number is excluded, and integer values must stay between -(2^53 - 1) and 2^53 - 1 so every conforming implementation can represent the value exactly. Reachability i