MCP 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 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 .
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 to a tool property: A call with then carries: The official C# SDK can generate that schema from a parameter attribute: 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. and therefore collide.
Control characters, spaces, and separators such as a colon are not valid suffix characters.
Only , , and properties can be mirrored.
JSON Schema is excluded, and integer values must stay between and so every conforming implementation can represent the value exactly.
Reachability is the rule most likely to surprise me.
An annotated property can be nested, but the path from the schema root must pass only through .
An annotation below , , , , , or another composition or conditional keyword is invalid.
A Streamable HTTP client must exclude an invalid tool from the returned result and should log the reason.
A stdio client may ignore these annotations because it has no HTTP headers to project.
Values have their own encoding rules.
Plain visible ASCII can travel as-is.
Non-ASCII text, control characters, leading or trailing whitespace, and strings that already look like the sentinel must be UTF-8/Base64 encoded inside that sentinel.
Boolean values become lowercase or ; mathematically integral JSON forms such as normalize to decimal .
If an optional argument is absent or explicitly , the client omits its header.
Make schema drift fail offline The sample draft PR turns those requirements into a dependency-free .NET 10 executable.
It scans the relevant JSON Schema subschema locations, ignores annotation-shaped literal data under keywords such as , records valid property paths, and fails malformed schemas before any network request.
The deterministic verifier covers twelve cases, including nested primitive properties, absent and arguments, non-ASCII and sentinel encoding, case-insensitive duplicates, the forbidden type, annotations below and , literal example data, invalid HTTP tokens, integral exponent notation, and both safe-integer boundaries.
I like this style of test because it catches two different regressions.
A server refactor can accidentally move an annotation behind a ; a client refactor can stop encoding a padded or Unicode value.
Both changes compile, but both break the transport contract.
At runtime, the server has another job.
It must decode recognized values and compare them with the body.
A missing, malformed, or different value is HTTP 400 with JSON-RPC error ().
When that mismatch suggests a stale schema, the client should refresh before retrying with the new definition.
Limits: routing metadata is not authorization These headers help infrastructure route, meter, and observe requests.
They do not prove that a caller may use the region, tenant, or resource named in the value.
An attacker who can choose the body can usually choose the matching header too, so the application still needs normal authentication and authorization checks.