Skip to content

feat: server multi-round-trip requests, part 1: input-required outcomes (T14) - #313

Draft
sideeffffect wants to merge 21 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t14-server-mrtr
Draft

sideeffffect wants to merge 21 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t14-server-mrtr

Conversation

@sideeffffect

@sideeffffect sideeffffect commented Nov 19, 2026 •

Copy link
Copy Markdown

T14 (part 1 of 2) — #252: server multi-round-trip requests

Layer 3 of a stack. Depends on #312 (T16), which depends on #311. Until those merge, this diff also shows their commits; the delta of this PR alone: sideeffffect/chimp@feat/t16-subscriptions-listen...feat/t14-server-mrtr

The request-state signer is in part 2 (next PR).

Asking the client for input

  • Tools, prompts, resources and resource templates can end with InputRequired instead of a result:
    InputRequired("name" -> InputRequired.elicitForm(message, schema))
      .and("llm", InputRequired.sample(params))
      .withRequestState(state)
    Kinds: elicitForm, elicitUrl, sample, listRoots. The constructor is private, so an outcome always has at least one request or a state.
  • Handler return types become unions: tools F[ToolResult[O] | InputRequired], prompts F[GetPromptResult | InputRequired], resources F[Either[ResourceError, List[ResourceContents]] | InputRequired]. Existing code compiles unchanged for covariant effects (Identity, Future, ZIO, cats IO).
  • On the retry the handler reads ctx.request.inputResponses / requestState (accessors elicitResult(key), samplingResult(key), rootsResult(key)), and can ask again for more rounds.

Rules the server enforces

  • An input request needing a capability the client did not declare → -32021, merged requiredCapabilities, HTTP 400. An empty elicitation: {} covers form mode only; URL mode needs elicitation.url.
  • inputResponses that is not an object, or has a value that is not a valid answer, or a non-string requestState → -32602, HTTP 400, before the handler runs.
  • Unknown answer keys are ignored. A missing answer should lead to a new InputRequired (fixtures and docs do this).
  • InputRequired on a legacy request → -32603 naming 2026-07-28.
  • test_missing_capability (from feat: request facts, per-request log level and -32021 (T8 follow-ups) #311) now really asks for sampling.

Wire and transport changes

  • Core fix: ResultType.InputRequired = "input_required" (was Incomplete / "incomplete"). InputRequiredResult.inputRequests is now optional, so a state-only result is valid.
  • Streaming HTTP (Ox, ZIO, Pekko) starts the handler and waits for its first message. If it ends with an error before sending anything, the client gets plain application/json with that status (needed for -32021 + 400); otherwise SSE as before. ServerStreamingHttpTransport.eventStream changes signature to (OutboundSink[F] => F[McpResponse]): F[Either[(StatusCode, Json), EventStream]]. On Ox the handler runs on ox.oxThreadFactory.

Tests, conformance, docs

  • New McpHandlerInputRequiredSpec; shared HTTP tests on Ox/ZIO/Pekko, shared stdio tests on sync/Ox/ZIO/Pekko, one sync HTTP test. All gates pass locally.
  • Fixtures: test_input_required_result_{elicitation,sampling,list_roots,multiple_inputs,multi_round,capabilities}, test_streaming_elicitation, prompt test_input_required_result_prompt.
  • Server conformance 2026-07-28: 133 → 151 checks pass. Removed from the baseline: server-stateless and input-required-result-{basic-elicitation,basic-sampling,basic-list-roots,capability-check,multiple-input-requests,multi-round,non-tool-request,result-type,missing-input-response,ignore-extra-params}.
  • Docs: new docs/server/mrtr.md; short notes in tools, prompts, resources and capabilities.

Open for review

  • The union return types (an invariant F must widen the value).
  • The deferred SSE decision: the handler starts before the stream is consumed; on Ox it runs on an unstructured thread that is interrupted when the stream ends.
  • 1119 changed lines, a little over the ~1000 target; splitting further would separate the outcome type from its transport support.

Stack

  1. #311 — T8 follow-ups
  2. #312 — T16 subscriptions/listen
  3. this PR — 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. #317 — 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.
…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