Skip to content

feat: client HTTP request headers on the stateless wire (T12) - #317

Draft
sideeffffect wants to merge 35 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t12-client-headers
Draft

sideeffffect wants to merge 35 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t12-client-headers

Conversation

@sideeffffect

@sideeffffect sideeffffect commented Nov 19, 2026 •

Copy link
Copy Markdown

T12 — closes #250: client HTTP request headers

Layer 7 of a stack. Depends on #316 (T10) and the PRs below it. The delta of this PR alone: sideeffffect/chimp@feat/t10-client-stateless...feat/t12-client-headers

Standard headers (stateless wire, every HTTP POST)

  • Mcp-Method = the JSON-RPC method, case preserved.
  • Mcp-Name = params.name on tools/call / prompts/get, params.uri on resources/read.
  • A value that is not plain ASCII, has leading/trailing spaces or control characters, or looks like the sentinel itself, is sent in the Base64 sentinel form.
  • Legacy requests are unchanged; stdio has no headers.

Custom headers from tool arguments

  • For a property marked x-mcp-header, the client mirrors the argument into Mcp-Param-<name> on the tools/call POST: plain ASCII strings as is, other strings Base64-sentinel, booleans true/false, integers as JSON text. null or an unannotated argument → no header.
  • The transport learns annotations from a tools/list result, so call listTools before callTool (documented).

Invalid annotations

  • On the stateless wire over HTTP, tools/list drops a tool whose x-mcp-header is invalid (empty, not a string, duplicate header name, a name with spaces, colons, non-ASCII or control characters, a number property, a property not on a plain chain of properties keys) and logs a warning; the other tools are kept. Over stdio the annotations are ignored.

Tests and conformance

  • Covered on the sync, ZIO, Ox and Pekko HTTP transports. testFull 427 passed, Integration 117 passed.
  • Client conformance 2026-07-28: 58 passed (was 24). Removed from the baseline http-custom-headers, http-invalid-tool-headers; http-standard-headers (not baselined) now passes 9/9.
  • Docs: docs/client/transport.md.

Stack

  1. #311 — T8 follow-ups
  2. #312 — T16 subscriptions/listen
  3. #313 — T14 part 1: input-required outcomes
  4. #314 — T14 part 2: request-state signer
  5. #315 — T13 x-mcp-header
  6. #316 — T10 client stateless lifecycle
  7. this PR — T12 client HTTP request headers
  8. #318 — T11 client automatic era detection

…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.
The client now owns the protocol version: McpClient sets it on the
transport through the new ClientTransport.setProtocolVersion, and the
HTTP transports lose their protocolVersion parameter. A stateless request
names its version in _meta, so the MCP-Protocol-Version header always
equals it; legacy requests use the version from initialize.

At 2026-07-28 the client:
- sends server/discover instead of initialize, and reads serverInfo from
  _meta, a top-level field, or falls back to "unknown"
- stamps protocol version, client info, client capabilities and the new
  logLevel option into every request's _meta
- retries once on -32022 with the newest common stateless version and
  keeps it; with no common version it fails with
  McpUnsupportedProtocolVersionException naming both lists
- treats a missing resultType as complete and fails on unknown and
  input_required results (no multi round-trip support yet)
- offers discover() and protocolVersion, and rejects the operations the
  stateless wire removed (ping, setLoggingLevel, subscribe, unsubscribe,
  progress, roots list_changed)

At a legacy version the logLevel option sends logging/setLevel once
after initialize. HTTP transports return a JSON-RPC error in the body of
an HTTP error response as the response, and the streaming ones open no
GET stream at a stateless version.

The conformance client handles request-metadata and
json-schema-ref-no-deref; both, and json-schema-2020-12-preservation,
leave the 2026-07-28 baseline.
At 2026-07-28 every POST of the HTTP transports (sync, ZIO, Ox, Pekko)
now carries the request headers that the spec requires:
- Mcp-Name in the Base64 sentinel form when the value is not printable
  ASCII, has leading or trailing whitespace, or looks like the sentinel
- Mcp-Param-<name> for each tools/call argument that the tool's input
  schema marks with x-mcp-header: strings plain or in the sentinel form,
  booleans as true/false, integers as JSON text, nothing for null

A stateless tools/list result loses the tools whose x-mcp-header
annotations are invalid (empty, not a string, not an HTTP token,
duplicated case-insensitively, on a non string/integer/boolean property
or off a plain properties chain); the transport logs a warning and keeps
the other tools. Legacy requests and stdio are unchanged.

The conformance client handles http-standard-headers,
http-custom-headers and http-invalid-tool-headers; the last two leave the
2026-07-28 baseline.
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant