server: SEP-2243 custom param-header (x-mcp-header) validation — prepare for upstream conformance PR 325 #1111

Upstream conformance PR 325 (modelcontextprotocol/conformance, plain-text ref) extends the server header scenarios to cover the currently-untested SEP-2243 param-presence checks. Dry-run against cmd/testserver (PR branch merged with their current main, 2026-07-22):

http-header-validation: 11/12. The single failure is the fail-open missing-Mcp-Method behavior disputed in their issue 323 (TypeScript SDK is also fail-open). Excluded from tier scoring while disputed; do NOT implement fail-closed until the dispute resolves.

http-custom-header-server-validation: 4/10 with an annotated fixture tool added. The 4 passes are all accept-cases, which a server that ignores X-Mcp-* headers passes trivially. Every reject-case fails, because mcpkit's server validates only the Mcp-Method / Mcp-Name routing headers (server/header_validation.go) and has no custom param-header enforcement. The client side has the full machinery (core/sep2243.go encode/extract + client/headers.go); the server side never grew the mirror.

Work:

1. Server-side validation for tools/call against x-mcp-header-annotated inputSchema properties, on BOTH wires (legacy dispatch + stateless callToolForStateless, per the known dispatch-parity failure mode):
   • decode =?base64?...?= wrapped values; reject invalid padding / non-alphabet chars
   • reject value mismatch between header and body argument
   • reject header omitted while the annotated value is present in the body
   • accept absent header when the annotated param is null/omitted (already trivially true, keep a test)
   • error code: scenario messaging is ambiguous between -32001 and mcpkit's -32020 HeaderMismatch; resolve against the SEP text during implementation
2. Fixture: add an x-mcp-header-annotated tool to cmd/testserver (dry-run used a 'custom_header_echo' tool with one annotated string property 'tenant')
3. Re-run the PR 325 branch scenarios; update conformance/known-gaps.yaml (the two check annotations currently claim local middleware coverage — sep-2243-server-not-expect-null passes trivially, sep-2243-server-reject-missing-required needs the real enforcement)

Not urgent until their PR 325 merges, but when it does, the server score degrades without this.