fix: enforce MCP parameter header requirements

Signed-off-by: lucarlig <luca.carlig@ibm.com>

Author: lucarlig

_context/wiki/architecture.md

@@ -85,6 +85,10 @@ backend and original tool name. When `UserConfig` contains that tool's input
 schema, it validates recognized `Mcp-Param-*` headers against the request body;
 it does not call backend `tools/list`. Without a published schema, parameter
 headers are unrecognized and forwarded without local validation.
+Published annotations are validated for MCP token, uniqueness, primitive type,
+and properties-only reachability constraints. Nested annotations read the exact
+argument path. Present non-null values require a matching header; absent or
+null values require no header.
 Parameter headers are forwarded unchanged; request plugins run afterward, so a
 plugin that changes an annotated argument also owns any resulting upstream
 mismatch.

_context/wiki/config.md

@@ -139,7 +139,12 @@ BackendMCPGateway
 annotations without calling backend `tools/list`. The control plane may omit the
 field or individual unannotated tools. Without a published schema, parameter
 headers are forwarded as unrecognized intermediary headers and are not locally
-validated.
+validated. A published annotation must name a non-empty, case-insensitively
+unique HTTP token on a `string`, `integer`, or `boolean` property reachable from
+the schema root through `properties` keys only. Nested properties use their
+exact property path. For a recognized annotation, a non-null argument requires
+an equal header; an absent or null argument requires the header to be absent.
+Integer values are limited to the IEEE 754 safe range.
 
 **Header apply order:** `passthrough_headers` → `add_headers` (override passthrough) → `remove_headers` (applied last).
 

_context/wiki/security.md

@@ -95,9 +95,14 @@ Backend header policy cannot add, remove, or replace MCP standard or parameter
 headers. For modern `tools/call`, the dataplane resolves the authenticated
 user, virtual host, backend, and original tool name before validating
 recognized `Mcp-Param-*` against the control-plane-published input schema. A
-recognized header/body mismatch fails closed with JSON-RPC `-32020`. When no
-schema is published, parameter headers are unrecognized and forwarded without
-local validation; their absence does not block the tool call.
+recognized missing, malformed, unexpected, conflicting repeated, or mismatched header fails closed
+with JSON-RPC `-32020`. Schema annotations also fail closed unless their names
+are non-empty, case-insensitively unique HTTP tokens, their properties have an
+allowed primitive type, and their paths are statically reachable through
+`properties` only. Nested values are checked at their exact path, and integers
+must remain in the IEEE 754 safe range. When no schema is published, parameter
+headers are unrecognized and forwarded without local validation; their absence
+does not block the tool call.
 Validation does not call backend `tools/list`. Parameter values are forwarded
 unchanged, while RMCP regenerates method, routed-name, and protocol-version
 headers. If a plugin later changes an annotated argument, the original header

_context/wiki/testing.md

@@ -35,7 +35,11 @@ Protocol-sensitive tests and fixtures must cover MCP `2026-07-28` and `2025-11-2
 These run in `cargo nextest run` with no Docker dependencies.
 
 Parameter-header integration tests verify that calls without a published tool
-schema skip local `Mcp-Param-*` validation and still reach the backend.
+schema skip local `Mcp-Param-*` validation and still reach the backend. Unit and
+integration coverage also includes missing, malformed, unexpected, repeated,
+and mismatched recognized headers; Base64 encoding; nested paths; numerically
+equivalent integers; and invalid annotation names, types, duplicates, and
+non-`properties` paths.
 
 ## MCP Conformance