Repository navigation
feat: x-mcp-header and request header validation (T13) - #315
Draft
sideeffffect wants to merge 31 commits into
Draft
sideeffffect wants to merge 31 commits into
sideeffffect wants to merge 31 commits into
Conversation
…Level Add RequestInfo (protocol version, client capabilities, client info, log level, progress token) and expose it as ServerContext.request. The handler builds it once per request and passes it to the transport's context factory, which replaces the bare progress-token argument. A modern (2026-07-28) request takes all facts from _meta. A legacy request gives only the protocol version (header or _meta) and the progress token, because the server keeps no state from initialize. StreamingServerContext.log now follows the per-request log level of a modern request: it sends notifications/message only at or above _meta logLevel, and none when the request sets no level, as the 2026-07-28 spec requires. Legacy requests keep receiving all messages.
…ontext Add serverLogicWithContext to tools, prompts, resources and resource templates. The logic receives the ServerContext, so it can read the request facts (protocol version, client capabilities, client info, log level) without a streaming server. Until now only streaming tools got a context.
A tool can now declare the client capabilities it needs with withRequiredClientCapabilities. When a modern (2026-07-28) tools/call targets such a tool and _meta clientCapabilities does not declare them, the request fails before any logic runs with -32021 MissingRequiredClientCapability, HTTP 400, and data.requiredCapabilities set to the tool's requirement, as the schema requires. The check runs in requestRejection, so a streaming transport answers with plain JSON and not an SSE stream. Capabilities are compared key by key, recursively for nested objects. Legacy requests carry no capabilities, so they are not checked.
RequestId decoded numeric ids only as Int. A request with a larger id (for example a millisecond timestamp, which the conformance harness sends) failed to decode as a request and was taken for a notification, so the server answered with an empty response. RequestId now also holds a Long; small numbers still decode as Int, so existing ids compare equal.
…ce fixtures The server-stateless scenario (2026-07-28) calls test_missing_capability without declaring sampling and expects -32021 with HTTP 400, and calls test_logging_tool without a logLevel and expects no notifications/message. test_missing_capability declares sampling as a required client capability; test_logging_tool logs once at every level and relies on the per-request log gate. Both checks now pass. The scenario stays in the baseline, because it also covers subscriptions/listen and other later work.
Describe ctx.request (RequestInfo) and which facts a modern and a legacy request give, serverLogicWithContext, the logLevel gate on ctx.log for modern requests, and withRequiredClientCapabilities with its -32021 rejection. Add -32021 to the table of modern request errors.
…og level The shared streaming tests run with a legacy client (Pekko) and with a modern 2026-07-28 client (ZIO, Ox). The modern client sends no _meta logLevel yet, so under the per-request log level rule it must receive no notifications/message. Each spec now states its client protocol version, and the log tests expect the messages for a legacy client and none for a modern one. This covers the log gate end to end over HTTP on all three backends.
server/discover was the era-agnostic bootstrap and skipped all checks. A discover that declares a version (in _meta or in the MCP-Protocol-Version header) is now a modern request and gets the same checks: -32602 for missing _meta keys, -32022 with the supported and requested versions for an unsupported version, -32020 for a header that differs from _meta, and the SEP-2243 Mcp-Method check, all with HTTP 400. A discover with no version, or a legacy one, is still answered, so a probing client can discover the server. Two ordering fixes follow the conformance harness: a header/_meta version mismatch is now reported (-32020) before an unsupported _meta version (-32022), and a modern HTTP request without the MCP-Protocol-Version header fails with -32020.
…ling NotificationPublisher lets application code publish tools, prompts and resources list changes and resource updates from any thread. Servers take it with withPublisher. A handler for a transport that can hold a stream open accepts a modern subscriptions/listen request, acknowledges the subset of the filter it honours, tags every message with the subscription id, and ends it with a successful listen result when the publisher closes. Modern discover advertises listChanged and resources.subscribe only when the server can publish them; legacy initialize is unchanged. Without a streaming transport, subscriptions/listen stays -32601.
The streaming HTTP transports answer an accepted subscriptions/listen request with an SSE stream that stays open: the acknowledgement first, then the publisher's notifications that the filter asks for. ZIO, Ox and Pekko each deliver into their own stream and cancel the subscription when the client closes the stream. A subscription is registered before it is acknowledged, and gets no notification before the acknowledgement, so an event published right after the client sees the acknowledgement is not lost. Shared HTTP tests run on all three backends.
All subscriptions of a stdio connection share its output and are told apart by the subscription id. The client ends one with notifications/cancelled naming the listen request. When the input ends, the server ends each open subscription with a successful listen result followed by notifications/cancelled. The sync, Ox, ZIO and Pekko stdio transports share this logic; the ZIO transport now serialises its writes, because notifications can arrive from other threads.
…e conformance fixtures The conformance server publishes tools and prompts list changes from the two fixture tools and closes its subscriptions on shutdown. The five subscriptions/listen checks of server-stateless now pass. The scenario stays in the baseline: only http-server-no-independent-requests-on-stream still fails, because it needs the test_streaming_elicitation tool (T14).
capabilities.md explains how to publish list changes and resource updates, which capabilities follow from a publisher, the listen stream rules over HTTP and stdio, and that a streaming transport is needed. resources.md points modern clients to the resourceSubscriptions filter.
…RequiredResult The 2026-07-28 schema names the MRTR result type input_required, not incomplete, and makes inputRequests optional (an input-required result needs at least one of inputRequests or requestState).
…d outcome A tools/call, prompts/get or resources/read handler can now return InputRequired (keyed form/URL elicitation, sampling and roots requests, plus an optional opaque request state) instead of its result. The client gets resultType input_required; on the retry the handler reads the answers and the state from RequestInfo. The server enforces the MRTR rules so handlers do not have to: an outcome always has requests or a state (by construction); an input request the client has no capability for fails with -32021, the missing requiredCapabilities and HTTP 400; malformed inputResponses or requestState fail with -32602 and HTTP 400 before the handler runs; unknown answer keys are ignored; an outcome on a legacy request becomes an internal error naming protocol version 2026-07-28.
A streaming HTTP server opened the 200 event stream before the handler ran, so a -32021 for an input request the client has no capability for could only travel inside it. The backends (Ox, ZIO, Pekko) now start the handler and wait for its first message: if the handler ends with an error that has its own HTTP status before it sends anything, that error goes as a plain application/json response with that status; otherwise the stream carries the messages and the response as before.
The stdio servers (sync, Ox, ZIO, Pekko) answer an input-required call, its retry and a -32021; the sync HTTP endpoint sends the -32021 with HTTP 400.
The conformance server now offers the MRTR fixture tools (elicitation, sampling, list_roots, multiple_inputs, multi_round, capabilities, test_streaming_elicitation) and the prompt test_input_required_result_prompt. test_missing_capability gets its real behaviour: it asks for sampling, so a client without that capability gets -32021 with HTTP 400. Eleven input-required scenarios and server-stateless leave the 2026-07-28 baseline; request-state and tampered-state stay until the request-state helper lands.
A new page explains how a handler asks for input with InputRequired, reads the answers and the request state on the retry, asks again for a missing answer, chooses by client capabilities, and which rules chimp enforces. The tools, prompts, resources and capabilities pages point to it.
A server configured with withRequestStateSigner signs the request state of each InputRequired outcome with HMAC-SHA256 under the owner's secret, together with an expiry and the identity of the request (method, tool or prompt name or resource URI, a digest of the arguments, and on a secured server the principal). On the retry the server verifies the state with a constant-time comparison before the handler runs, and the handler sees the original state. A changed, expired or foreign state fails with -32602 and HTTP 400, and the handler does not run.
The conformance server signs its request states with a random per-process secret, and offers test_input_required_result_request_state and test_input_required_result_tampered_state. Both scenarios pass and leave the 2026-07-28 baseline.
Explains how to give a server a RequestStateSigner, what the signature covers, how a failed verification is answered, and the security notes: secret size and storage, rotation, no confidentiality, no single use.
Tool.withMcpHeader marks an input property, given by its name or by a chain of properties keys, so the generated inputSchema carries the x-mcp-header annotation. It works for derived and raw JSON schemas. The tool builder checks the spec constraints when the tool is built: inputJson, input and withMcpHeader throw IllegalArgumentException, as the tool name check does, for an empty name, a name outside the HTTP token syntax or with control characters, a duplicate name (ignoring case), a property that is not string, integer or boolean, and a property not reachable from the root through properties keys only. McpHeaders also holds the Base64 sentinel decoding and the header and argument comparison, which the server uses in the next step.
A modern tools/call over HTTP must mirror every argument that its tool
marks with x-mcp-header in the Mcp-Param-{name} header. The server
rejects with -32020 and HTTP 400 a header that is missing for a present
argument, present for a null or absent argument, malformed, or does
not match: numbers compare numerically, other values literally.
Mcp-Param headers that match no annotated property are ignored.
Mcp-Name and Mcp-Param values in the Base64 sentinel form are decoded
before the comparison; a malformed sentinel or a value with invalid
characters is a -32020. Legacy requests and stdio are unaffected.
A shared trait runs the x-mcp-header and Base64 sentinel cases over raw HTTP against the plain and the streaming transport, and the ZIO, Ox and Pekko specs mix it in. A rejection must be a plain JSON -32020 with HTTP 400, also on the streaming transport.
The http-custom-header-server-validation scenario needs a tool with a string property marked x-mcp-header. With test_custom_header it passes (10/10), so its entry leaves the 2026-07-28 baseline.
tools.md shows how to mark an input property with withMcpHeader, the constraints the builder enforces, and a warning not to mark sensitive parameters. capabilities.md (the protocol version page) adds the Mcp-Param rules, the Base64 sentinel decoding and the -32020 row.
This was referenced Nov 19, 2026
…owledged A subscription sent its acknowledgement first and set its acknowledged flag after. Over stdio the acknowledgement is written and flushed at once, so a client could read it and publish before the flag was set; the event was then dropped. This made the stdio subscription test wait forever for a tools/list_changed notification. Delivery now takes the same lock as the acknowledgement and the final result: an event published while the acknowledgement is on its way waits for it, and no notification follows the final result. A unit test publishes from another thread while the acknowledgement is being sent, which fails without the fix. The stdio tests now read the server output on their own thread and fail after 10 seconds instead of blocking in readLine.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
T13 — closes #251:
x-mcp-headerand request header validationLayer 5 of a stack. Depends on #314 → #313 → #312 → #311. The delta of this PR alone: sideeffffect/chimp@feat/t14-request-state...feat/t13-mcp-header
Tool DSL
inputSchemacarriesx-mcp-header. Anx-mcp-headeralready in a raw schema is kept and validated.Tool/ServerToolget a last fieldmcpHeaders: List[McpHeader] = Nil, so existing calls still compile.require, same style astool(name)) for: an empty name, a name outside HTTP token syntax or with control characters, a duplicate name in one tool ignoring case, a property type other than string/integer/boolean, a property not reachable from the root throughpropertieskeys only.Header validation (modern requests over HTTP)
Mcp-NameandMcp-Param-*values in the Base64 sentinel form (=?base64?...?=) are decoded before comparing; padding, alphabet and UTF-8 are checked strictly. A malformed sentinel, or a plain value outside visible ASCII/space/tab, →-32020. A value without the full wrapper is compared literally.x-mcp-headerproperty of atools/call: a present argument needs its header with the same value (numbers numerically,42.0==42; booleans astrue/false; strings literally) → else-32020, HTTP 400. UnmatchedMcp-Param-*headers are ignored.Tests, conformance, docs
McpServerHeaderHttpTests(plain + streaming transports, on ZIO, Ox, Pekko: 24 tests) plus unit and tool-builder tests.testFull390 passed, Integration 117 passed.test_custom_headerwith a stringregionproperty markedRegion.--scenario http-custom-header-server-validation: 10/10, 0 warnings (was 1/6).--scenario http-header-validation: 14/14, 0 warnings. Removedhttp-custom-header-server-validationfrom the baseline (keeping it made the direct run report a stale entry).docs/server/tools.md(marking properties, the constraints, a warning not to mark sensitive parameters); header rules and Base64 decoding indocs/server/capabilities.md.Open for review
-32020. The spec only says the server "MUST NOT expect" the header then; this is the stricter reading.docsExtension(tapir drops it onOptionfields). A field inside a nested case class becomes a$refand cannot be marked; the builder says so.Stack
subscriptions/listenx-mcp-header