feat: SEP-2243 Mcp-Param-* mirroring — client emission + server validation

Protocol crate (turul-mcp-protocol-2026-07-28/headers.rs): pure SEP-2243
logic shared by both sides — scan_x_mcp_headers() (annotation discovery at
any nesting depth; constraints: non-empty, tchar field-name syntax,
case-insensitive uniqueness, string/integer/boolean only),
encode_param_value()/decode_param_value() (string/integer/boolean
conversion, JS safe-integer range, =?base64?...?= sentinel incl. the
self-matching-sentinel re-encode rule). Unit tests reproduce all five spec
encoding examples. base64 workspace dep added.

Server: the tools/call handler validates every annotated parameter's
mirrored header against the body argument (sentinel-decoded; integers
compared numerically). Value-without-header, header-without-value, or a
decoded mismatch -> -32001 HeaderMismatch at HTTP 400. The transport
surfaces request headers to handlers via the rpc session metadata (2026
path); the inline 2026 JSON path maps -32001 to 400 alongside -32003.
Invalid annotations on the server's own tool log a warning and skip
enforcement (a conforming client never lists such a tool).

Client: tools/list excludes tool definitions with invalid x-mcp-header
values (spec MUST; warning logged) and captures per-tool bindings BEFORE the
2025-vocabulary remap (the typed 2025 JsonSchema cannot carry the
annotation). tools/call mirrors annotated arguments into Mcp-Param-{name}
headers via the new Transport::send_request_with_extra_headers (default
delegates to send_request — non-HTTP transports MAY ignore the annotations
per spec). Without a cached schema the call goes out headerless per the spec
note; the schema-stale auto-retry is left to the application.

Tests: mcp_param_2026.rs — 4 real-HTTP server cases (match, Base64-sentinel
match, omitted-header rejection, mismatch rejection). Revert-and-fail:
with the validation block compiled out, both negative cases fail and both
positive controls pass — recorded. Client closed loop in
e2e_2026_real_server.rs: the validating server rejects missing mirrors, so
the green client calls (plain ASCII + Base64 sentinel) prove emission.
CI: mcp_param_2026 gate in ci.yml + ci-gates.sh.

Author: hortovanyi

.github/workflows/ci.yml

@@ -51,6 +51,8 @@ jobs:
         run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test error_mapping_2026
       - name: 2026 MRTR (input_required round trip, -32003 capability gate)
         run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test mrtr_2026
+      - name: 2026 Mcp-Param-* mirroring (x-mcp-header validation)
+        run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test mcp_param_2026
       - name: protocol-2026 compliance + upstream wire fixtures
         run: cargo test -p turul-mcp-protocol-2026-07-28 --features compliance
       - name: Bilingual client (not in default-members)

CHANGELOG.md

@@ -44,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added (2026-06-10)
 
+- **SEP-2243 `Mcp-Param-*` custom-header mirroring (client emission + server validation).** Completes the deferred remainder of the request-metadata headers work. Protocol crate: pure SEP-2243 logic in `headers.rs` — `scan_x_mcp_headers()` (annotation discovery at any nesting depth with the full constraint set: non-empty, `tchar` syntax, case-insensitive uniqueness, string/integer/boolean only), `encode_param_value()` / `decode_param_value()` (string/integer/boolean conversion, JS safe-integer range, `=?base64?…?=` sentinel incl. the self-matching-sentinel re-encode rule; unit tests reproduce all five spec encoding examples). Server: the tools/call handler validates every annotated parameter's mirrored header against the body argument (sentinel-decoded; integers compared numerically) — value-without-header, header-without-value, or decoded mismatch → `-32001 HeaderMismatch` at HTTP 400 (the transport surfaces request headers to handlers via the rpc session metadata; the inline 2026 JSON path now maps `-32001` to 400 alongside `-32003`). Client: `tools/list` rejects tool definitions with invalid `x-mcp-header` values (excluded + warning, per spec) and captures per-tool bindings BEFORE the 2025-vocabulary remap (which cannot carry the annotation); `tools/call` mirrors annotated arguments into `Mcp-Param-{name}` headers via a new `Transport::send_request_with_extra_headers` (default delegates to `send_request` — non-HTTP transports MAY ignore the annotations). Tests: `mcp_param_2026.rs` (4 real-HTTP server cases; revert-and-fail recorded — both negative cases fail with validation disabled) and a closed-loop client e2e (the validating server rejects missing mirrors, so the green client call proves emission; covers plain ASCII and Base64-sentinel values). Not implemented (acceptable per spec): the client's optional schema-stale auto-retry (`tools/list` + retry on rejection is left to the application).
 - **Schema pin re-vendored (content sha256 `1bf94a60…`, fixture pin `1304c8fe`).** One substantive upstream change: `ElicitationCompleteNotificationParams` extracted into a named interface extending `NotificationParams` (surface 159 → 160). The Rust binding already modeled the optional `_meta`, so the previously recorded deviation resolved upstream. ADR-027 revision log + COMPLIANCE.md/schema README hash records updated.
 - **Docs/ADR reconciliation to implemented behavior**: ADR-029 §CI surface rewritten to the as-built lanes (the prescribed `cargo test --workspace` matrices never compiled — spec-pinned workspace members trip the ADR's own mutex; per-crate matrix is the operative shape); ADR-025 revision entry recording the shim's branch reality (still consumed by four non-frozen crates; manifest carries an unpublishable 0.4.0 from the version sweep; the framework-wide cut remains 0.4.0 release-prep work); `docs/plans/2026-07-28-schema-coverage-matrix.md` marked STALE/superseded (authoritative coverage = COMPLIANCE.md + the compliance harness); COMPLIANCE.md elicitation-union and extension-crate-name notes refreshed.
 - **MRTR (SEP-2322): `InputRequiredResult` production (server) and consumption (client).** Server: a tool returning the new `McpError::InputRequired { input_requests, request_state }` sentinel (2026 protocol crate; NOT a wire error — the only return channel available to tool impls) is converted by the `tools/call` handler into a successful `InputRequiredResult` (`resultType: "input_required"`), after enforcing that every input request targets a capability the client declared in that request's `_meta` `clientCapabilities` — undeclared → `-32003 MissingRequiredClientCapability` at HTTP 400 (the 2026 JSON-framed response path now dispatches inline so the HTTP status can reflect the JSON-RPC outcome; SSE-framed responses inherently stay 200). On the retry leg, `CallToolRequestParams.inputResponses`/`requestState` are surfaced to tools via `SessionContext::input_responses()` / `mrtr_request_state()` (requestState documented as attacker-controlled). Client: `call_tool` surfaces `resultType: "input_required"` as the new `McpClientError::InputRequired` carrying `inputRequests`/`requestState`; the application gathers inputs and retries via `call_tool_with_input_responses(name, args, responses, request_state)` (fresh JSON-RPC id; 2026 connections only). New `ClientConfig.declared_capabilities` (elicitation/sampling/roots, all off by default) feeds both the 2026 per-request `_meta` and the 2025 `initialize` capabilities — previously hardcoded empty. Tests: `mrtr_2026.rs` (real-HTTP two-leg round trip + `-32003`/400 capability rejection; the suite does not compile against the pre-slice tree — the sentinel variant did not exist) and a full client-driven MRTR e2e in `e2e_2026_real_server.rs`. Limitations (tracked): MRTR production is wired for `tools/call` only (`resources/read`/`prompts/get` handlers have no input hooks yet); the framework does not generate or verify `requestState` integrity (HMAC is the tool author's concern).

crates/turul-http-mcp-server/src/streamable_http.rs

@@ -2093,9 +2093,21 @@ impl StreamableHttpHandler {
         );
         let broadcaster_any = Arc::new(broadcaster) as Arc<dyn std::any::Any + Send + Sync>;
 
+        // 2026: surface the request headers to handlers — Mcp-Param-* validation
+        // happens at the tools/call handler, the only layer that knows the
+        // tool's inputSchema annotations.
+        #[cfg(feature = "protocol-2026-07-28")]
+        let handler_metadata: std::collections::HashMap<String, serde_json::Value> = context
+            .headers
+            .iter()
+            .map(|(k, v)| (k.clone(), serde_json::Value::String(v.clone())))
+            .collect();
+        #[cfg(feature = "protocol-2025-11-25")]
+        let handler_metadata = std::collections::HashMap::new();
+
         let session_context = SessionContext {
             session_id: session_id.clone(),
-            metadata: std::collections::HashMap::new(),
+            metadata: handler_metadata,
             broadcaster: Some(broadcaster_any),
             timestamp: chrono::Utc::now().timestamp_millis() as u64,
             extensions: std::collections::HashMap::new(),
@@ -2122,8 +2134,10 @@ impl StreamableHttpHandler {
                 )
                 .await;
             let status = match &response {
+                // -32003 MissingRequiredClientCapability and -32001
+                // HeaderMismatch both mandate HTTP 400.
                 turul_mcp_json_rpc_server::JsonRpcResponse::Error(err)
-                    if err.error.code == -32003 =>
+                    if matches!(err.error.code, -32001 | -32003) =>
                 {
                     StatusCode::BAD_REQUEST
                 }

crates/turul-mcp-client/src/client.rs

@@ -31,6 +31,10 @@ use turul_mcp_protocol_2025_11_25::{
 pub type NotificationCallback = Arc<dyn Fn(&str, Option<&Value>) + Send + Sync>;
 
 /// Main MCP client
+/// Per-tool SEP-2243 bindings: tool name → `(header name, argument JSON
+/// pointer, declared type)` per `x-mcp-header` annotation.
+type ParamBindingMap = std::collections::HashMap<String, Vec<(String, String, String)>>;
+
 pub struct McpClient {
     /// Transport layer — `Arc<BoxedTransport>` (no Mutex) so concurrent
     /// `call_tool`/`list_tools`/etc. go through the transport in parallel.
@@ -48,6 +52,11 @@ pub struct McpClient {
     response_consumer_handle: Arc<parking_lot::Mutex<Option<tokio::task::JoinHandle<()>>>>,
     /// Cached tool list (invalidated by `notifications/tools/list_changed`)
     cached_tools: Arc<RwLock<Option<Vec<Tool>>>>,
+    /// SEP-2243 `Mcp-Param-*` bindings per tool, from the raw 2026 `tools/list`
+    /// result. The public `Tool` vocabulary (2025 types) cannot carry the
+    /// `x-mcp-header` annotation, so the bindings are captured before the
+    /// type remap.
+    cached_param_bindings: Arc<RwLock<ParamBindingMap>>,
     /// Cached resource list (invalidated by `notifications/resources/list_changed`)
     cached_resources: Arc<RwLock<Option<Vec<Resource>>>>,
     /// Cached prompt list (invalidated by `notifications/prompts/list_changed`)
@@ -128,6 +137,7 @@ impl McpClient {
             request_counter: Arc::new(std::sync::atomic::AtomicU64::new(0)),
             response_consumer_handle: Arc::new(parking_lot::Mutex::new(None)),
             cached_tools: Arc::new(RwLock::new(None)),
+            cached_param_bindings: Arc::new(RwLock::new(std::collections::HashMap::new())),
             cached_resources: Arc::new(RwLock::new(None)),
             cached_prompts: Arc::new(RwLock::new(None)),
             notification_callback,
@@ -815,9 +825,15 @@ impl McpClient {
         );
 
         let response = self.send_request_internal(request).await?;
-        let tools = crate::protocol::v2026_07_28::parse_list_tools(
-            &response.get("result").cloned().unwrap_or(Value::Null),
-        )?;
+        let raw_result = response.get("result").cloned().unwrap_or(Value::Null);
+        let tools = crate::protocol::v2026_07_28::parse_list_tools(&raw_result)?;
+
+        // Capture the SEP-2243 Mcp-Param bindings before the vocabulary remap
+        // drops the x-mcp-header annotations.
+        {
+            let bindings = crate::protocol::v2026_07_28::collect_param_bindings(&raw_result);
+            *self.cached_param_bindings.write().await = bindings;
+        }
 
         debug!(count = tools.len(), "Retrieved tools");
         Ok(tools)
@@ -887,6 +903,64 @@ impl McpClient {
         parse(&response.get("result").cloned().unwrap_or(Value::Null))
     }
 
+    /// SEP-2243: the `Mcp-Param-*` headers for a `tools/call`, from the cached
+    /// bindings. Empty when the tool schema has not been fetched yet — per the
+    /// spec the call then goes out without custom headers, and a rejecting
+    /// server prompts the application to `list_tools()` and retry.
+    #[cfg(any(feature = "client-bilingual", feature = "client-2026-07-28-only"))]
+    async fn mcp_param_headers_for(
+        &self,
+        tool_name: &str,
+        arguments: &Value,
+    ) -> Vec<(String, String)> {
+        let cache = self.cached_param_bindings.read().await;
+        match cache.get(tool_name) {
+            Some(bindings) => {
+                crate::protocol::v2026_07_28::encode_param_headers(bindings, arguments)
+            }
+            None => Vec::new(),
+        }
+    }
+
+    #[cfg(any(feature = "client-bilingual", feature = "client-2026-07-28-only"))]
+    async fn send_2026_07_28_with_extra_headers<T>(
+        &self,
+        method: &str,
+        extra: Value,
+        extra_headers: &[(String, String)],
+        parse: impl Fn(&Value) -> McpClientResult<T>,
+    ) -> McpClientResult<T> {
+        let meta = crate::protocol::v2026_07_28::request_meta(
+            &self.config.client_info.name,
+            &self.config.client_info.version,
+            &self.config.declared_capabilities,
+        );
+        let request = self.build_request(
+            method,
+            crate::protocol::v2026_07_28::params_with_meta(&meta, extra),
+        );
+        if !self.session.is_ready().await {
+            return Err(crate::error::SessionError::NotInitialized.into());
+        }
+        let response = tokio::time::timeout(
+            self.config.timeouts.request,
+            self.transport
+                .send_request_with_extra_headers(request, extra_headers),
+        )
+        .await
+        .map_err(|_| McpClientError::Timeout)??;
+        if let Some(error) = response.get("error") {
+            let code = error.get("code").and_then(|c| c.as_i64()).unwrap_or(-1) as i32;
+            let message = error
+                .get("message")
+                .and_then(|m| m.as_str())
+                .unwrap_or("Unknown error");
+            let data = error.get("data").cloned();
+            return Err(McpClientError::server_error(code, message, data));
+        }
+        parse(&response.get("result").cloned().unwrap_or(Value::Null))
+    }
+
     /// Reject an operation whose method was removed from the 2026-07-28 core when the
     /// connection negotiated 2026. The method remains available on a 2025-11-25 connection.
     async fn reject_if_2026_07_28(&self, _method: &str) -> McpClientResult<()> {
@@ -906,10 +980,12 @@ impl McpClient {
 
         #[cfg(any(feature = "client-bilingual", feature = "client-2026-07-28-only"))]
         if self.negotiated_version().await == Some(crate::version::McpVersion::V2026_07_28) {
+            let extra_headers = self.mcp_param_headers_for(name, &arguments).await;
             return self
-                .send_2026_07_28(
+                .send_2026_07_28_with_extra_headers(
                     "tools/call",
                     json!({ "name": name, "arguments": arguments.clone() }),
+                    &extra_headers,
                     crate::protocol::v2026_07_28::parse_call_tool,
                 )
                 .await;

crates/turul-mcp-client/src/protocol/v2026_07_28.rs

@@ -79,7 +79,80 @@ pub(crate) fn parse_list_tools(
     result: &Value,
 ) -> McpClientResult<Vec<turul_mcp_protocol_2025_11_25::Tool>> {
     let r: p::tools::ListToolsResult = serde_json::from_value(result.clone())?;
-    r.tools.iter().map(remap).collect()
+    // SEP-2243: clients on Streamable HTTP MUST reject tool definitions whose
+    // x-mcp-header annotations violate the constraints — exclude the tool and
+    // log a warning, so one malformed definition doesn't block the rest.
+    r.tools
+        .iter()
+        .filter(|tool| {
+            let schema = serde_json::to_value(&tool.input_schema).unwrap_or_default();
+            match p::headers::scan_x_mcp_headers(&schema) {
+                Ok(_) => true,
+                Err(reason) => {
+                    tracing::warn!(
+                        tool = %tool.name,
+                        %reason,
+                        "excluding tool from tools/list: invalid x-mcp-header annotation"
+                    );
+                    false
+                }
+            }
+        })
+        .map(remap)
+        .collect()
+}
+
+/// SEP-2243: per-tool `Mcp-Param-*` bindings from a raw `tools/list` result —
+/// `(header name, argument JSON pointer, declared type)` per annotation.
+/// Tools with invalid annotations yield no entry (they are excluded from the
+/// list result anyway).
+pub(crate) fn collect_param_bindings(
+    result: &Value,
+) -> std::collections::HashMap<String, Vec<(String, String, String)>> {
+    let mut map = std::collections::HashMap::new();
+    let Some(tools) = result.get("tools").and_then(|t| t.as_array()) else {
+        return map;
+    };
+    for tool in tools {
+        let (Some(name), Some(schema)) = (
+            tool.get("name").and_then(|n| n.as_str()),
+            tool.get("inputSchema"),
+        ) else {
+            continue;
+        };
+        if let Ok(bindings) = p::headers::scan_x_mcp_headers(schema)
+            && !bindings.is_empty()
+        {
+            map.insert(
+                name.to_string(),
+                bindings
+                    .into_iter()
+                    .map(|b| (b.header_name, b.argument_pointer, b.schema_type))
+                    .collect(),
+            );
+        }
+    }
+    map
+}
+
+/// Encode the `Mcp-Param-*` headers for a `tools/call`, per the cached
+/// bindings: absent/null arguments omit their header (per the SEP-2243
+/// client-behavior table); unencodable values also omit (the server rejects
+/// the call, which is the correct surfacing of a schema-violating argument).
+pub(crate) fn encode_param_headers(
+    bindings: &[(String, String, String)],
+    arguments: &Value,
+) -> Vec<(String, String)> {
+    let mut headers = Vec::new();
+    for (header_name, pointer, _schema_type) in bindings {
+        let Some(value) = arguments.pointer(pointer).filter(|v| !v.is_null()) else {
+            continue;
+        };
+        if let Some(encoded) = p::headers::encode_param_value(value) {
+            headers.push((format!("Mcp-Param-{header_name}"), encoded));
+        }
+    }
+    headers
 }
 
 pub(crate) fn parse_call_tool(

crates/turul-mcp-client/src/transport.rs

@@ -118,6 +118,17 @@ pub trait Transport: Send + Sync {
     /// Send a request and wait for response
     async fn send_request(&self, request: Value) -> McpClientResult<Value>;
 
+    /// Send a request with additional per-request HTTP headers (SEP-2243
+    /// `Mcp-Param-*` mirrors). Non-HTTP transports MAY ignore the annotations
+    /// entirely, so the default delegates to [`Self::send_request`].
+    async fn send_request_with_extra_headers(
+        &self,
+        request: Value,
+        _extra_headers: &[(String, String)],
+    ) -> McpClientResult<Value> {
+        self.send_request(request).await
+    }
+
     /// Send a request and return response with headers (for initialization)
     async fn send_request_with_headers(&self, request: Value)
     -> McpClientResult<TransportResponse>;

crates/turul-mcp-client/src/transport/http.rs

@@ -688,6 +688,43 @@ impl Transport for HttpTransport {
         Ok(result)
     }
 
+    async fn send_request_with_extra_headers(
+        &self,
+        request: Value,
+        extra_headers: &[(String, String)],
+    ) -> McpClientResult<Value> {
+        if !self.is_connected() {
+            return Err(TransportError::ConnectionFailed("Not connected".to_string()).into());
+        }
+        let mut request = request;
+        if request.get("id").is_none() {
+            request["id"] = Value::String(self.next_request_id());
+        }
+        self.update_stats(|stats| stats.requests_sent += 1);
+
+        let mut req_builder = self
+            .client
+            .post(self.endpoint.clone())
+            .header("Content-Type", "application/json")
+            .header("Accept", MCP_POST_ACCEPT)
+            .header("MCP-Protocol-Version", self.protocol_version.read().clone());
+        req_builder = self.apply_request_metadata_headers(req_builder, &request);
+        for (name, value) in extra_headers {
+            req_builder = req_builder.header(name, value);
+        }
+        req_builder = self.apply_auth_override(req_builder);
+        if let Some(ref session_id) = *self.session_id.lock() {
+            req_builder = req_builder.header("Mcp-Session-Id", session_id);
+        }
+
+        let response = req_builder
+            .json(&request)
+            .send()
+            .await
+            .map_err(|e| TransportError::Http(format!("Failed to send request: {}", e)))?;
+        self.handle_response(response).await
+    }
+
     async fn send_request_with_headers(
         &self,
         request: Value,