T14 - server MRTR (multi round trip requests) handling

[kubinio123]

Target branch: 2026-07-28-protocol-support

Requires:

• T5 - MRTR (multi round trip requests) types #243
• T8 - serve 2026-07-28 requests next to legacy requests #246

A chimp server can ask the client for input while it handles tools/call, prompts/get or resources/read, without keeping any state between the first request and the retry. This follows the Multi Round-Trip Requests pattern that replaces server-initiated requests in 2026-07-28. Legacy clients are not affected.

Requesting input

• A tool, prompt or resource handler can end a request with an input-required outcome instead of a result. The outcome names the input requests under keys the handler chooses, and may carry an opaque request state. The request kinds are form elicitation, URL elicitation, sampling and roots.
• The client receives resultType: input_required with inputRequests and requestState. Only tools/call, prompts/get and resources/read can answer this way. Every other request never does.
• On the retry the handler reads the client's answers under the same keys, and the request state it produced. A handler that never asks for input behaves as today.
• A handler can ask again on a retry, with a new state, for as many rounds as it needs.
• A handler can read the client's capabilities and choose what to ask for, for example sampling when the client supports it and a form otherwise.

Rules the server enforces, so handlers do not have to

• An input-required outcome carries at least one of input requests or request state.
• No input request reaches a client that did not declare the matching capability. Such a request fails with -32021, requiredCapabilities naming the missing capability, and HTTP 400.
• inputResponses that are not an object, or whose value does not have the shape of the expected answer, fail with -32602.
• Keys in inputResponses that the handler did not ask for are ignored.
• A retry that lacks an answer the handler needs leads to a new input-required outcome, not an error. The fixture tools behave this way and the docs recommend it.
• An input-required outcome on a legacy request becomes an internal error with a message that names the required protocol version.

Request state

• Chimp ships a helper that produces and verifies an integrity-protected request state: HMAC-SHA256 over a payload the handler chooses, plus an expiry and an identifier of the originating request, keyed by a secret the server owner provides.
• A state that was changed, has expired, or belongs to another request or principal is rejected with -32602. The handler never runs on an unverified state when it uses the helper.
• The state is opaque to the client and the client echoes it verbatim. The server treats it as untrusted input.

Coverage

• The rules above hold for the sync and streaming servers, over HTTP and stdio, on ZIO, Ox and Pekko.
• The conformance server offers the fixture tools test_input_required_result_elicitation, test_input_required_result_sampling, test_input_required_result_list_roots, test_input_required_result_request_state, test_input_required_result_multiple_inputs, test_input_required_result_multi_round, test_input_required_result_tampered_state, test_input_required_result_capabilities, test_streaming_elicitation, and the prompt test_input_required_result_prompt. The tool test_missing_capability from T8 gets its real behaviour here: it asks for sampling, so a client without that capability gets -32021.

Spec:

• MRTR - Supported Requests
• MRTR - Server Requirements
• MRTR - Error Handling
• MRTR - Security Considerations
• Tools - Input Required Tool Results
• Prompts - Getting a Prompt
• Resources - Reading Resources
• Elicitation - URL Mode Flow
• Basic - Error Codes

Conformance scenarios that must pass after this task:

• Server: input-required-result-basic-elicitation, input-required-result-basic-sampling, input-required-result-basic-list-roots, input-required-result-request-state, input-required-result-multiple-input-requests, input-required-result-multi-round, input-required-result-missing-input-response, input-required-result-non-tool-request, input-required-result-result-type, input-required-result-tampered-state, input-required-result-capability-check, input-required-result-ignore-extra-params, input-required-result-validate-input. These 13 leave the 2026-07-28 baseline.
• server-stateless leaves the baseline: its three MRTR checks (sep-2575-server-rejects-undeclared-capability, sep-2575-missing-capability-http-400, sep-2575-http-server-no-independent-requests-on-stream) pass

Docs: yes.

• New page docs/server/mrtr.md (added to the toctree): how a handler asks for input, how it reads the answers on the retry, the request state helper and the secret it needs, the capability rule, and the advice to ask again instead of failing when an answer is missing.
• docs/server/tools.md, docs/server/prompts.md, docs/server/resources.md: one line each that points to the new page.