feat(server): mode-aware MRTR capability gating (elicitation.url, sampling.tools)

The -32003 gate in input_required_to_result checked only top-level
capability presence; a URL-mode elicit request passed against a form-only
client, and tool-enabled sampling passed against bare sampling:{}.

Spec contracts now enforced:
- Elicitation §Capabilities: "Servers MUST NOT send elicitation requests
  with modes that are not supported by the client"; "an empty capabilities
  object is equivalent to declaring support for form mode only". URL mode
  requires elicitation.url; form mode rides the empty object (an explicit
  url-only object does NOT imply form).
- Sampling §Tools in Sampling: "Servers MUST NOT send tool-enabled
  sampling requests to Clients that have not declared support for tool use
  via the sampling.tools capability" — tools/toolChoice present requires
  sampling.tools.

Red phase recorded: url_mode_elicitation_requires_the_url_subcapability and
tool_enabled_sampling_requires_the_tools_subcapability failed (200
input_required instead of 400 -32003) before the gate refinement.
Gates: scripts/ci-gates.sh all → ALL GATES PASSED.

Closes spec-compliance driver gaps CF/GAP-CF-1 + CF/GAP-CF-2 (P1).

Author: hortovanyi

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Mode-aware MRTR capability gating (2026-06-11).** The server's `-32003` gate on `InputRequiredResult` now enforces sub-capabilities, not just top-level presence: URL-mode elicitation requires the client's `elicitation.url` declaration ("Servers MUST NOT send elicitation requests with modes that are not supported by the client"; an empty `elicitation: {}` declares form-only), and tool-enabled sampling (`tools`/`toolChoice` present) requires `sampling.tools` ("Servers MUST NOT send tool-enabled sampling requests to Clients that have not declared support"). Closes spec-compliance driver gaps **CF/GAP-CF-1 + CF/GAP-CF-2 (both P1)**; red-phase wire tests in `mrtr_2026.rs`.
 - **`roots/list` removed from the 2026 default surface (2026-06-11).** On 2026-07-28, roots is a client feature: the server requests roots via MRTR input requests and never hosts an inbound `roots/list` RPC; `notifications/roots/list_changed` has no binding in the pinned schema. The builder's `roots/list` + roots-notification registrations are now gated to the `protocol-2025-11-25` opt-in; on the 2026 default they answer 404 + `-32601` like every other non-2026 method. Closes spec-compliance driver gap **CF/GAP-CF-4 (P1)**; red-phase recorded in `error_mapping_2026.rs`.
 - **Client MRTR completion for `resources/read` + `prompts/get`, and `resultType` discipline (2026-06-11, ADR-030 revision log).** The bilingual client's `parse_read_resource`/`parse_get_prompt` now surface `InputRequiredResult` as `McpClientError::InputRequired` (previously a serde "missing field" error that discarded `inputRequests`/`requestState`), with retry APIs `read_resource_with_input_responses` / `get_prompt_with_input_responses` mirroring `call_tool_with_input_responses`. All 2026 result parsers now enforce basic §Responses ("a resultType of any value unrecognized by the client MUST be considered invalid"): unknown discriminators are `ProtocolError::InvalidResponse` instead of being treated as complete results. Closes spec-compliance driver gaps CF/GAP-CF-3, PRM/PR-2026-02, RES-G1, PAT/G3, BP-1 (all P1 except PAT/G3). Real-server e2e round-trips added; revert-and-fail recorded.
 - **Origin-header validation (DNS-rebinding protection) on the HTTP transport (2026-06-11, ADR-031).** Streamable HTTP §Security requires: "Servers MUST validate the `Origin` header … If the `Origin` header is present and invalid, servers MUST respond with HTTP 403 Forbidden." New `OriginPolicy` on `ServerConfig` — default `SameOriginOrLoopback` (Origin absent → allowed; loopback or Host-matching origins → allowed; anything else → 403), `AllowList(Vec<String>)` additive allowlist, `Disabled` opt-out for upstream-enforced deployments. Enforced at both transport handler entries (streamable + legacy session path), so hyper and Lambda deployments inherit it; OPTIONS preflight and `.well-known` routes exempt. Builder knobs: `HttpMcpServerBuilder::origin_policy` and `McpServer::builder().origin_policy(...)`. Wire tests in `crates/turul-mcp-server/tests/origin_validation_2026.rs` (revert-and-fail proven: disabling the gate fails 3 tests). On the Lambda builder, an explicit CORS configuration derives the policy (`cors_allow_all_origins()` → `Disabled`, an origin list → `AllowList`) unless `.origin_policy()` overrides it — `turul-http-mcp-server`'s blanket `enable_cors` flag deliberately does NOT derive (see ADR-031 §CORS-derived policy). Closes spec-compliance driver gap **TX/GAP-1 (P0)**. **Behavior change:** cross-origin browser clients now require an explicit `AllowList` (previously implicitly admitted via CORS `*`).

crates/turul-mcp-server/src/handlers/mod.rs

@@ -48,9 +48,13 @@ fn extract_cursor_from_params(params: &Option<Value>) -> Option<turul_mcp_protoc
 /// MRTR (SEP-2322): convert a provider's `McpError::InputRequired` outcome
 /// into a successful `InputRequiredResult` value, after enforcing that every
 /// input request targets a capability the client declared in the request's
-/// `_meta` `clientCapabilities` (undeclared → `-32003`, HTTP 400). Shared by
-/// the three methods permitted to return `input_required`: `tools/call`,
-/// `resources/read`, `prompts/get`.
+/// `_meta` `clientCapabilities` (undeclared → `-32003`, HTTP 400). Gating is
+/// mode-aware: URL-mode elicitation needs `elicitation.url`, form mode rides
+/// the empty object ("an empty capabilities object is equivalent to declaring
+/// support for form mode only"), and tool-enabled sampling (`tools` /
+/// `toolChoice` present) needs `sampling.tools`. Shared by the three methods
+/// permitted to return `input_required`: `tools/call`, `resources/read`,
+/// `prompts/get`.
 #[cfg(feature = "protocol-2026-07-28")]
 pub(crate) fn input_required_to_result(
     input_requests: Option<turul_mcp_protocol::input_required::InputRequests>,
@@ -63,12 +67,37 @@ pub(crate) fn input_required_to_result(
         for request in requests.values() {
             #[allow(deprecated)]
             let missing = match request {
-                InputRequest::Elicit(_) if caps.elicitation.is_none() => {
-                    Some(serde_json::json!({ "elicitation": {} }))
-                }
-                InputRequest::CreateMessage(_) if caps.sampling.is_none() => {
-                    Some(serde_json::json!({ "sampling": {} }))
-                }
+                InputRequest::Elicit(elicit) => match &caps.elicitation {
+                    None => Some(serde_json::json!({ "elicitation": {} })),
+                    Some(e) => {
+                        use turul_mcp_protocol::elicitation::ElicitRequestParams;
+                        match &elicit.params {
+                            // URL mode needs the explicit url sub-capability.
+                            ElicitRequestParams::Url(_) if e.url.is_none() => {
+                                Some(serde_json::json!({ "elicitation": { "url": {} } }))
+                            }
+                            // Form mode: an empty capabilities object declares
+                            // form-only support; an explicit url-only object
+                            // does NOT imply form.
+                            ElicitRequestParams::Form(_) if e.form.is_none() && e.url.is_some() => {
+                                Some(serde_json::json!({ "elicitation": { "form": {} } }))
+                            }
+                            _ => None,
+                        }
+                    }
+                },
+                InputRequest::CreateMessage(create) => match &caps.sampling {
+                    None => Some(serde_json::json!({ "sampling": {} })),
+                    // Tool-enabled sampling needs the tools sub-capability.
+                    Some(sc)
+                        if (create.params.tools.is_some()
+                            || create.params.tool_choice.is_some())
+                            && sc.tools.is_none() =>
+                    {
+                        Some(serde_json::json!({ "sampling": { "tools": {} } }))
+                    }
+                    Some(_) => None,
+                },
                 InputRequest::ListRoots(_) if caps.roots.is_none() => {
                     Some(serde_json::json!({ "roots": {} }))
                 }

crates/turul-mcp-server/tests/mrtr_2026.rs

@@ -208,6 +208,193 @@ async fn undeclared_capability_is_rejected_with_32003() {
 #[allow(dead_code)]
 fn _t(_: HashMap<String, String>) {}
 
+// ---- Sub-capability gating (elicitation modes; sampling.tools) ----
+
+/// Demands a URL-mode elicitation — needs `elicitation.url` declared.
+#[derive(McpTool, Clone, Default)]
+#[tool(name = "url_gated", description = "Needs a URL elicitation", output = String)]
+struct UrlGatedTool {}
+
+impl UrlGatedTool {
+    async fn execute(&self, session: Option<SessionContext>) -> McpResult<String> {
+        if let Some(session) = &session
+            && session.input_responses().is_some()
+        {
+            return Ok("done".to_string());
+        }
+        let mut requests = InputRequests::new();
+        requests.insert(
+            "auth".to_string(),
+            InputRequest::Elicit(ElicitRequest::new_url(
+                "Authorize via browser",
+                "el-1",
+                "https://example.test/authorize",
+            )),
+        );
+        Err(McpError::InputRequired {
+            input_requests: Some(requests),
+            request_state: None,
+        })
+    }
+}
+
+/// Demands tool-enabled sampling — needs `sampling.tools` declared.
+#[derive(McpTool, Clone, Default)]
+#[tool(name = "sampler", description = "Needs tool-enabled sampling", output = String)]
+struct SamplingGatedTool {}
+
+impl SamplingGatedTool {
+    async fn execute(&self, session: Option<SessionContext>) -> McpResult<String> {
+        if let Some(session) = &session
+            && session.input_responses().is_some()
+        {
+            return Ok("done".to_string());
+        }
+        #[allow(deprecated)]
+        let request = {
+            use turul_mcp_protocol::sampling::{
+                CreateMessageRequest, CreateMessageRequestParams, SamplingMessage,
+            };
+            let mut params =
+                CreateMessageRequestParams::new(vec![SamplingMessage::user_text("hi")], 64);
+            params.tools = Some(vec![turul_mcp_protocol::tools::Tool::new(
+                "lookup",
+                turul_mcp_protocol::ToolSchema::object(),
+            )]);
+            CreateMessageRequest::new(vec![], 64).with_params(params)
+        };
+        let mut requests = InputRequests::new();
+        requests.insert("s1".to_string(), InputRequest::CreateMessage(request));
+        Err(McpError::InputRequired {
+            input_requests: Some(requests),
+            request_state: None,
+        })
+    }
+}
+
+async fn start_subcap_server() -> String {
+    let port = std::net::TcpListener::bind("127.0.0.1:0")
+        .unwrap()
+        .local_addr()
+        .unwrap()
+        .port();
+    let server = McpServer::builder()
+        .name("mrtr-2026-subcap")
+        .version("0.4.0")
+        .tool(UrlGatedTool::default())
+        .tool(SamplingGatedTool::default())
+        .bind_address(format!("127.0.0.1:{port}").parse().unwrap())
+        .build()
+        .expect("build 2026 server");
+    tokio::spawn(async move {
+        server.run().await.ok();
+    });
+    let url = format!("http://127.0.0.1:{port}/mcp");
+    let probe = reqwest::Client::new();
+    for _ in 0..50 {
+        if probe.get(&url).send().await.is_ok() {
+            break;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+    }
+    url
+}
+
+async fn call_tool_with_caps(
+    url: &str,
+    tool: &str,
+    capabilities: serde_json::Value,
+) -> (reqwest::StatusCode, serde_json::Value) {
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(url)
+        .header("Accept", "application/json")
+        .header("MCP-Protocol-Version", "2026-07-28")
+        .header("Mcp-Method", "tools/call")
+        .header("Mcp-Name", tool)
+        .json(&serde_json::json!({
+            "jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {
+                "name": tool,
+                "arguments": {},
+                "_meta": meta_with_capabilities(capabilities)
+            }
+        }))
+        .send()
+        .await
+        .expect("tools/call POST");
+    let status = resp.status();
+    let body: serde_json::Value = resp.json().await.unwrap_or_default();
+    (status, body)
+}
+
+/// Elicitation §Capabilities: "Servers MUST NOT send elicitation requests
+/// with modes that are not supported by the client" and "an empty
+/// capabilities object is equivalent to declaring support for form mode
+/// only" — a URL-mode request against `elicitation: {}` must be -32003.
+#[tokio::test]
+async fn url_mode_elicitation_requires_the_url_subcapability() {
+    let url = start_subcap_server().await;
+
+    // Form-only declaration (empty object): URL mode rejected.
+    let (status, body) =
+        call_tool_with_caps(&url, "url_gated", serde_json::json!({ "elicitation": {} })).await;
+    assert_eq!(status, 400, "url mode vs form-only client: {body}");
+    assert_eq!(body["error"]["code"], -32003, "{body}");
+
+    // URL declared: passes the gate, input_required comes back.
+    let (status, body) = call_tool_with_caps(
+        &url,
+        "url_gated",
+        serde_json::json!({ "elicitation": { "url": {} } }),
+    )
+    .await;
+    assert_eq!(status, 200, "{body}");
+    assert_eq!(body["result"]["resultType"], "input_required", "{body}");
+}
+
+/// Elicitation §Capabilities: form mode rides both the empty object and an
+/// explicit form declaration.
+#[tokio::test]
+async fn form_mode_elicitation_passes_with_empty_capability_object() {
+    let url = start_server().await;
+    let (status, body) = call_gated_echo(
+        &url,
+        serde_json::json!({ "elicitation": {} }),
+        serde_json::json!({}),
+    )
+    .await;
+    assert_eq!(status, 200, "{body}");
+    assert_eq!(body["result"]["resultType"], "input_required", "{body}");
+}
+
+/// Sampling §Tools in Sampling: "Servers MUST NOT send tool-enabled sampling
+/// requests to Clients that have not declared support for tool use via the
+/// sampling.tools capability."
+#[tokio::test]
+async fn tool_enabled_sampling_requires_the_tools_subcapability() {
+    let url = start_subcap_server().await;
+
+    // Bare sampling declaration: tool-enabled request rejected.
+    let (status, body) =
+        call_tool_with_caps(&url, "sampler", serde_json::json!({ "sampling": {} })).await;
+    assert_eq!(
+        status, 400,
+        "tool-enabled sampling vs bare sampling: {body}"
+    );
+    assert_eq!(body["error"]["code"], -32003, "{body}");
+
+    // sampling.tools declared: passes the gate.
+    let (status, body) = call_tool_with_caps(
+        &url,
+        "sampler",
+        serde_json::json!({ "sampling": { "tools": {} } }),
+    )
+    .await;
+    assert_eq!(status, 200, "{body}");
+    assert_eq!(body["result"]["resultType"], "input_required", "{body}");
+}
+
 // ---- MRTR on resources/read and prompts/get ----
 
 /// Resource that demands an elicitation before serving content.

docs/plans/2026-07-28-spec-compliance.md

@@ -778,11 +778,11 @@ in the same slice as the fix.
   - Requirement: "Invalid or expired tokens MUST receive a HTTP 401 response"; "MCP servers MUST implement OAuth 2.0 Protected Resource Metadata (RFC 9728)" — https://modelcontextprotocol.io/specification/draft/basic/authorization (§Token Handling, §Overview #4)
   - Current: Implementation exists and is unit-tested (middleware.rs::test_missing_bearer_returns_401; build_http_challenge_response at crates/turul-http-mcp-server/src/streamable_http.rs:2775-2796 adds WWW-Authenticate + Cache-Control: no-store + MCP-Protocol-Version), and Lambda streaming has a transport test (turul-mcp-aws-lambda/src/handler.rs:1533-1634). But none of the nine 2026 suites (crates/turul-mcp-
   - Fix: New crates/turul-mcp-server/tests/oauth_2026.rs real-HTTP suite (Builder → handler → wire bytes per CLAUDE.md §Test Coverage Discipline #2/#3), wired into ci.yml + scripts/ci-gates.sh; governed by ADR-021/ADR-022
-- [ ] **CF/GAP-CF-1** — No elicitation mode-level capability gating on the server MRTR gate
+- [x] **CF/GAP-CF-1** — No elicitation mode-level capability gating on the server MRTR gate — **FIXED 2026-06-11** (mode-aware gate in `input_required_to_result`; wire tests `url_mode_elicitation_requires_the_url_subcapability` / `form_mode_elicitation_passes_with_empty_capability_object`, red-phase recorded)
   - Requirement: "Servers MUST NOT send elicitation requests with modes that are not supported by the client" and "an empty capabilities object is equivalent to declaring support for form mode only" — https://modelcontextprotocol.io/specification/draft/client/elicitation §Capabilities
   - Current: input_required_to_result checks only caps.elicitation.is_none() (crates/turul-mcp-server/src/handlers/mod.rs:66-68). A tool emitting InputRequest::Elicit with ElicitRequestParams::Url passes the gate even when the client declared elicitation:{} (form-only per spec) or elicitation:{form:{}} — the URL-mode request is sent to a client that never declared url support.
   - Fix: crates/turul-mcp-server/src/handlers/mod.rs (input_required_to_result): match ElicitRequestParams::Url against caps.elicitation.url, Form against form-or-empty; add -32003 wire tests for the url-vs-form-only case in crates/turul-mcp-server/tests/mrtr_2026.rs. Governed by ADR-027 (2026 spec target); 
-- [ ] **CF/GAP-CF-2** — No sampling.tools gating for tool-enabled sampling input requests
+- [x] **CF/GAP-CF-2** — No sampling.tools gating for tool-enabled sampling input requests — **FIXED 2026-06-11** (`tool_enabled_sampling_requires_the_tools_subcapability`, red-phase recorded)
   - Requirement: "Servers MUST NOT send tool-enabled sampling requests to Clients that have not declared support for tool use via the sampling.tools capability" — https://modelcontextprotocol.io/specification/draft/client/sampling §Tools in Sampling
   - Current: The gate checks only caps.sampling.is_none() (crates/turul-mcp-server/src/handlers/mod.rs:69-70). An InputRequest::CreateMessage whose params carry tools/toolChoice passes when the client declared bare sampling:{} without the tools sub-capability (SamplingCapabilities.tools, crates/turul-mcp-protocol-2026-07-28/src/initialize.rs:113-117 — the binding even documents 'Server MUST get an error if it 
   - Fix: crates/turul-mcp-server/src/handlers/mod.rs (input_required_to_result): when InputRequest::CreateMessage params.tools/tool_choice is Some, require caps.sampling.tools; add a -32003 wire test in crates/turul-mcp-server/tests/mrtr_2026.rs. Governed by ADR-027. Optionally also gate include_context this