T13 - server new headers validation and x-mcp-header in the tool DSL

[kubinio123]

Target branch: 2026-07-28-protocol-support

Requires:

• T8 - serve 2026-07-28 requests next to legacy requests #246

A chimp server validates the request headers the spec requires against the request body and rejects every mismatch. A tool can declare which of its input properties travel as HTTP headers, and the server validates those headers too.

Standard header validation (2026-07-28 requests over HTTP)

• A request without Mcp-Method, or whose Mcp-Method differs from the body method, fails with -32020 and HTTP 400.
• A tools/call, prompts/get or resources/read request without Mcp-Name, or whose Mcp-Name differs from params.name or params.uri, fails with -32020 and HTTP 400.
• Header names are matched case-insensitively. Header values are compared case-sensitively, after trimming the whitespace HTTP allows around a value and after decoding the Base64 sentinel form where the spec permits it (Mcp-Name, Mcp-Param-*).
• Legacy requests and stdio are not affected.

Custom header validation

• For every input property marked with x-mcp-header, a tools/call request that carries the matching Mcp-Param-<name> header is accepted only when the decoded header value equals the argument value. A different value fails with -32020 and HTTP 400.
• A value in the Base64 sentinel form is decoded before the comparison. A malformed sentinel (bad padding, invalid characters) fails with -32020. A value without the sentinel wrapper is compared literally.
• Integer values are compared numerically, so 42.0 in the header equals 42 in the body.
• When the argument is present in the body but the header is missing, the request fails with -32020. When the argument is null or absent, no header is expected.
• Mcp-Param-* headers that match no annotated property are ignored.

Tool DSL

• A tool can mark an input property with x-mcp-header and a header name, for schemas derived from a case class and for schemas given as JSON. The generated inputSchema carries the annotation so clients can mirror the argument.
• Building a tool fails at construction when an annotation breaks the spec constraints: empty name, name outside HTTP token syntax, control characters, a name used twice in one tool regardless of case, a property whose type is not string, integer or boolean, or a property that is not reachable from the schema root through properties keys only.

Coverage

• The rules above hold for the sync and streaming HTTP servers on ZIO, Ox and Pekko.
• The conformance server offers at least one tool with a string property marked x-mcp-header, so the custom header scenario has something to exercise.

Spec:

• Streamable HTTP - Standard Request Headers
• Streamable HTTP - Schema Extension
• Streamable HTTP - Value Encoding
• Streamable HTTP - Server Behavior for Custom Headers
• Streamable HTTP - Case Sensitivity
• Streamable HTTP - Server Validation
• Tools - x-mcp-header

Conformance scenarios that must pass after this task (2026-07-28 run):

• http-header-validation and http-custom-header-server-validation. Both are pending in the harness, so they are not scored and do not touch the baseline. They must pass when run directly with --scenario <name> --spec-version 2026-07-28.

Docs: yes.

• docs/server/tools.md: how to mark an input property with x-mcp-header, the constraints the builder enforces, and the warning not to mark sensitive parameters.
• docs/server/protocol.md: the header validation rules and the -32020 error.