Client auto-resolves InputRequiredResult via existing callbacks (SEP-2322)

Client.call_tool/get_prompt/read_resource now resolve InputRequiredResult
automatically by dispatching the embedded sampling/elicitation/roots
input_requests to the same callbacks that already serve legacy server-to-client
RPCs, then retrying with the collected input_responses + echoed request_state
until a terminal result arrives. allow_input_required is removed from Client;
manual control is via client.session.<method>(..., allow_input_required=True).

- New client/_input_required.py: pure method-agnostic driver. max_rounds=10
  default; state-only legs back off 50ms doubling to 250ms cap (counter resets
  on any leg with input_requests). request_state passed through byte-exact.
  InputRequiredRoundsExceededError on cap; MCPError when a callback returns
  ErrorData.
- ClientSession: extracted _dispatch_input_request from the _on_request match
  so the legacy RPC path and the driver share one dispatch table.
  get_prompt/read_resource gain the allow_input_required overload set.
- Client: input_required_max_rounds field; shared _drive_input_required helper;
  call_tool/get_prompt/read_resource collapse to a single signature returning
  the bare result type.
- examples/stories/mrtr promoted from deferred stub to runnable.
- Conformance fixture sep-2322-client-request-state rewritten to drive the
  same five wire-shape checks via the auto-loop.
- docs/advanced/multi-round-trip.md + docs_src/mrtr/tutorial003.py updated.

Author: maxisbey

.github/actions/conformance/client.py

@@ -22,7 +22,7 @@
     http-standard-headers                   - Connect, call a tool (Mcp-* headers checked)
     http-invalid-tool-headers               - List tools, call every surfaced tool (x-mcp-header filter)
     elicitation-sep1034-client-defaults     - Elicitation with default accept callback
-    sep-2322-client-request-state           - Drive the manual MRTR retry surface
+    sep-2322-client-request-state           - Drive the MRTR auto-loop (SEP-2322)
     auth/client-credentials-jwt             - Client credentials with private_key_jwt
     auth/client-credentials-basic           - Client credentials with client_secret_basic
     auth/*                                  - Authorization code flow (default for auth scenarios)
@@ -374,46 +374,28 @@ async def run_elicitation_defaults(server_url: str) -> None:
 
 @register("sep-2322-client-request-state")
 async def run_mrtr_client(server_url: str) -> None:
-    """Drive the manual MRTR retry surface against the SEP-2322 client mock.
-
-    The mock speaks the modern lifecycle (server/discover, no initialize) and
-    inspects the wire params of each tools/call round, so this exercises the
-    explicit allow_input_required=True path rather than an auto-loop: round 1
-    receives an InputRequiredResult, the fixture fulfils the elicitation
-    locally, then round 2 retries with input_responses + the echoed
-    request_state. Passing request_state straight off the typed result -- a
-    str when the server sent one, None when it didn't -- lets the
-    serializer's exclude_none drop the key in the no-state case without a
-    branch here. The unrelated call between rounds proves MRTR params don't
-    leak across tools, and the no-result-type call must parse as a complete
-    CallToolResult with no retry.
+    """Drive the SEP-2322 client mock through `Client.call_tool`'s auto-loop.
+
+    The mock inspects raw `tools/call` params, so registering an
+    `elicitation_callback` and letting the driver run is enough to satisfy
+    all five wire-shape checks: the driver echoes `request_state` byte-exact
+    and omits it when the server sent none, every retry mints a fresh
+    JSON-RPC id, the unrelated call between auto-loops carries no MRTR
+    params, and the no-`resultType` response parses as a terminal
+    `CallToolResult` so the driver never retries it.
     """
-    async with Client(server_url, mode=client_mode()) as client:
-        await client.list_tools()
-        confirm = {"confirm": types.ElicitResult(action="accept", content={"confirmed": True})}
 
-        r1 = await client.call_tool("test_mrtr_echo_state", {}, allow_input_required=True)
-        assert isinstance(r1, types.InputRequiredResult)
-
-        await client.call_tool("test_mrtr_unrelated", {})
+    async def confirm(
+        context: ClientRequestContext, params: types.ElicitRequestParams
+    ) -> types.ElicitResult | types.ErrorData:
+        return types.ElicitResult(action="accept", content={"confirmed": True})
 
-        await client.call_tool(
-            "test_mrtr_echo_state",
-            {},
-            input_responses=confirm,
-            request_state=r1.request_state,
-            allow_input_required=True,
-        )
+    async with Client(server_url, mode=client_mode(), elicitation_callback=confirm) as client:
+        await client.list_tools()
 
-        r2 = await client.call_tool("test_mrtr_no_state", {}, allow_input_required=True)
-        assert isinstance(r2, types.InputRequiredResult)
-        await client.call_tool(
-            "test_mrtr_no_state",
-            {},
-            input_responses=confirm,
-            request_state=r2.request_state,
-            allow_input_required=True,
-        )
+        await client.call_tool("test_mrtr_echo_state", {})
+        await client.call_tool("test_mrtr_unrelated", {})
+        await client.call_tool("test_mrtr_no_state", {})
 
         result = await client.call_tool("test_mrtr_no_result_type", {})
         assert isinstance(result, types.CallToolResult)

docs/advanced/multi-round-trip.md

@@ -33,40 +33,37 @@ Everything else in that file (the explicit `input_schema`, the hand-built `CallT
 
 ## The client side
 
-`call_tool` will not hand you an `InputRequiredResult` unless you opt in.
+`Client` runs the loop for you.
 
-!!! check
-    Call a tool that needs input without opting in and `call_tool` raises:
+Register the callbacks the server might ask for (`elicitation_callback`, `sampling_callback`, `list_roots_callback`) and call the tool. When an `InputRequiredResult` arrives, `Client` dispatches each entry in `input_requests` to the matching callback, retries with the answers and the echoed `request_state`, and keeps going until a `CallToolResult` comes back:
 
-    ```text
-    Server returned InputRequiredResult; pass allow_input_required=True to receive it and retry call_tool(..., input_responses=..., request_state=result.request_state).
-    ```
+```python title="client.py" hl_lines="12 13"
+--8<-- "docs_src/mrtr/tutorial003.py"
+```
 
-    That is deliberate. Most call sites expect a result or an exception, not a third thing in the
-    middle of the happy path, and pyright agrees: without the flag, `call_tool` is typed to return
-    a plain `CallToolResult`.
+* That `elicitation_callback` is the same one a pre-2026 server's back-channel `elicitation/create` would have hit. One callback serves both eras.
+* `call_tool` returns a plain `CallToolResult`. The intermediate rounds are invisible to the caller.
+* `get_prompt` and `read_resource` drive the same loop.
 
-Pass `allow_input_required=True` and the result reaches you intact:
+!!! check
+    Leave the callback off and the loop fails on the first round: the SDK's stand-in callback
+    answers every elicitation with an error, and `call_tool` raises `MCPError` with the message
+    *"Elicitation not supported"*.
 
-```python
-result.result_type     # 'input_required'
-result.request_state   # 'provision-v1'
-result.input_requests  # {'region': ElicitRequest(method='elicitation/create', params=ElicitRequestFormParams(...))}
-```
+The loop is bounded. `Client(..., input_required_max_rounds=10)` is the default cap; a server that keeps returning `InputRequiredResult` past it makes `call_tool` raise. If a round carries only `request_state` and no `input_requests`, `Client` sleeps briefly (50ms doubling to a 250ms ceiling) before retrying, so a server that is just saying *"not done yet"* isn't busy-polled.
 
-### The retry loop
+### Driving the loop yourself
 
-Now you own the loop. There is no automatic driver yet; `while isinstance(result, InputRequiredResult)` **is** the API:
+The auto-loop holds nothing between calls. If you need to see each round (to persist `request_state` across a process restart, to show the user what was asked, to bail early) drop to the underlying session, where `allow_input_required=True` hands you the union directly:
 
-```python title="client.py" hl_lines="13-15 17-20"
+```python title="client.py" hl_lines="13 14 20"
 --8<-- "docs_src/mrtr/tutorial002.py"
 ```
 
-* `allow_input_required=True` widens the return type to `CallToolResult | InputRequiredResult`. That union is exactly what the `isinstance` is narrowing.
+* `client.session.call_tool(..., allow_input_required=True)` widens the return type to `CallToolResult | InputRequiredResult`. The `isinstance` is what narrows it back.
+* `request_state` is now in your hands. Write it down between legs and the conversation can resume from a fresh process.
 * For every entry in `input_requests` you put an `InputResponse` under the **same key** in `input_responses`. `fulfil` is where your UI goes; this one hard-codes the answer.
 * Same tool name, same `arguments`, every leg. The retry is the original call carried out again, not a new method.
-* `request_state=result.request_state`: copy it across. Never inspect it, never invent it.
-* When the server has everything it needs it returns a `CallToolResult` and the loop exits.
 
 ## A 2026-07-28 result
 
@@ -88,9 +85,8 @@ Now you own the loop. There is no automatic driver yet; `while isinstance(result
 
 * At 2026-07-28 a server that needs input mid-call **returns** an `InputRequiredResult`. It never opens a request to the client.
 * `input_requests` is what it needs. `request_state` is an opaque resume token only the server reads.
-* The client answers by calling the **same tool again** with `input_responses=` and `request_state=`.
-* By default `call_tool` raises on an `InputRequiredResult`; `allow_input_required=True` opts in and widens the return type.
-* The manual `while isinstance(result, InputRequiredResult)` loop is the whole client API; there is no auto-retry driver yet.
+* `Client` runs the retry loop for you: register `elicitation_callback` / `sampling_callback` / `list_roots_callback` and `call_tool` returns a plain `CallToolResult`. `input_required_max_rounds` (default 10) bounds it.
+* To inspect or persist rounds, use `client.session.call_tool(..., allow_input_required=True)` and own the `while isinstance(result, InputRequiredResult)` loop yourself.
 * The server side is the **low-level** `Server` only; `@mcp.tool()` has no sugar for this yet.
 
 This is the mechanism that replaces server-initiated sampling and the rest of the push-style back-channel; see **Deprecated features**.

docs/migration.md

@@ -395,9 +395,13 @@ For an in-process `Client(server)` (where `server` is a `Server` or `MCPServer`
 
 `Client.send_ping()` is deprecated (ping is removed in 2026-07-28); pin `mode='legacy'` if you need it.
 
-### `call_tool` can return `InputRequiredResult` (opt-in)
+### `InputRequiredResult` handling differs between `Client` and `ClientSession`
 
-For protocol 2026-07-28, a `tools/call` request may return an `InputRequiredResult` asking the client to supply additional input and retry. By default `call_tool` (on `ClientSession`, `Client`, and `ClientSessionGroup`) still returns `CallToolResult` and raises `RuntimeError` if the server requests input. Pass `allow_input_required=True` to receive the `InputRequiredResult` instead, then retry with `input_responses=` / `request_state=`.
+For protocol 2026-07-28, `tools/call`, `prompts/get`, and `resources/read` may return an `InputRequiredResult` asking the client to supply additional input (sampling, elicitation, roots) and retry.
+
+On the high-level `Client`, `call_tool`, `get_prompt`, and `read_resource` resolve this automatically: they dispatch each requested input to the matching callback (`sampling_callback`, `elicitation_callback`, `list_roots_callback`) and retry until a final result is returned, so the call still returns the bare `CallToolResult` / `GetPromptResult` / `ReadResourceResult`. The round limit is `Client(input_required_max_rounds=...)` (default 10). Earlier v2 prereleases exposed an `allow_input_required` parameter on these `Client` methods; that parameter has been removed. For manual control use `client.session.call_tool(..., allow_input_required=True)`. Note that `read_timeout_seconds` now bounds each underlying round, not the whole loop; wrap the call in `anyio.fail_after(...)` for a whole-loop bound.
+
+On `ClientSession`, `call_tool` / `get_prompt` / `read_resource` still return the bare result and raise `RuntimeError` if the server requests input. Pass `allow_input_required=True` to receive the `InputRequiredResult` instead, then drive the loop yourself with `input_responses=` / `request_state=`. `ClientSessionGroup.call_tool` accepts the same flag.
 
 ### `call_tool` mirrors `x-mcp-header` arguments into `Mcp-Param-*` headers (SEP-2243)
 

docs_src/mrtr/tutorial002.py

@@ -10,10 +10,10 @@ def fulfil(request: InputRequest) -> InputResponse:
 
 
 async def provision(client: Client, name: str) -> CallToolResult:
-    result = await client.call_tool("provision", {"name": name}, allow_input_required=True)
+    result = await client.session.call_tool("provision", {"name": name}, allow_input_required=True)
     while isinstance(result, InputRequiredResult):
         responses = {key: fulfil(request) for key, request in (result.input_requests or {}).items()}
-        result = await client.call_tool(
+        result = await client.session.call_tool(
             "provision",
             {"name": name},
             input_responses=responses,

docs_src/mrtr/tutorial003.py

@@ -0,0 +1,14 @@
+from mcp_types import ElicitRequestParams, ElicitResult
+
+from mcp import Client
+from mcp.client import ClientRequestContext
+
+
+async def handle_elicitation(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
+    return ElicitResult(action="accept", content={"region": "eu-west-1"})
+
+
+async def main() -> None:
+    async with Client("http://127.0.0.1:8000/mcp", elicitation_callback=handle_elicitation) as client:
+        result = await client.call_tool("provision", {"name": "orders"})
+        print(result.content)

examples/stories/manifest.toml

@@ -34,6 +34,9 @@ multi_connection = true
 # progress + log notifications dropped on the modern streamable-HTTP path pending SSE wiring
 xfail = ["http-asgi:modern"]
 
+[story.mrtr]
+era = "modern"
+
 [story.legacy_elicitation]
 era    = "legacy"
 status = "legacy"
@@ -140,7 +143,6 @@ fixed_port    = 8000                            # issuer/PRM metadata bake in :8
 
 [deferred]
 caching       = "client honouring + per-result override unlanded"
-mrtr          = "#2898 — InputRequiredResult runtime"
 subscriptions = "#2901 — Client.listen / ServerEventBus"
 tasks         = "extensions capability map + tasks runtime"
 apps          = "#2896 — extensions capability map"

examples/stories/mrtr/README.md

@@ -1,30 +1,54 @@
 # mrtr
 
-Multi-round tool results: a 2026-era tool call returns
-`resultType: "input_required"` with a `requestState` HMAC instead of pushing an
-`elicitation/create` request. The client fulfils the input and resubmits, and
-the server resumes from the carried state. The story will show both the
-auto-fulfil helper and a manual resubmit loop.
-
-**Status: not yet implemented** ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)).
-The lowlevel registration surface is in this base —
-[#2967](https://github.com/modelcontextprotocol/python-sdk/pull/2967)
-(`ae13ede`) widened the tool/prompt/resource handler return types to include
-`InputRequiredResult`. The runnable story is deliberately a follow-up PR to
-keep this one reviewable.
+Multi-round tool result: on the 2026-07-28 protocol a tool that needs user
+input mid-call **returns** `resultType: "input_required"` with embedded
+`inputRequests` and an opaque `requestState`, instead of pushing a
+server→client request. The client fulfils the embedded requests and retries the
+original `tools/call` carrying `inputResponses` and the echoed `requestState`.
+The story shows both the `Client` auto-loop (one `await call_tool`, callbacks
+fired transparently) and a manual `client.session` loop (the persistable form).
+
+## Run it
+
+```bash
+# HTTP — the client self-hosts the server on a free port, runs, then tears it
+# down (the InputRequiredResult round-trip is 2026-era only)
+uv run python -m stories.mrtr.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.mrtr.client --http --server server_lowlevel
+```
+
+## What to look at
+
+- `client.py` `main` — the auto-loop is invisible at the call site:
+  `Client(target, mode=mode, elicitation_callback=on_elicit)` then
+  `await client.call_tool("deploy", ...)`. The same `on_elicit` callback the
+  legacy push path uses is dispatched for each embedded `inputRequests` entry.
+- `client.py` manual block — `client.session.call_tool(...,
+  allow_input_required=True)` returns the raw `InputRequiredResult` so
+  `request_state` can be persisted between rounds; the retry is just another
+  `tools/call` with `input_responses=` / `request_state=`.
+- `server.py` `deploy` — `ctx.input_responses` / `ctx.request_state` read the
+  retry payload; the first round returns
+  `InputRequiredResult(input_requests={...}, request_state=...)`, the second
+  returns the final string.
+- `server_lowlevel.py` — same wire contract via `params.input_responses` /
+  `params.request_state` and a hand-built `InputRequiredResult`.
+
+## Caveats
+
+- **Loop bound.** The auto-loop gives up after `input_required_max_rounds`
+  (default 10) with `InputRequiredRoundsExceededError`; raise it on the
+  `Client` ctor or drop to the manual loop.
+- **`requestState` integrity is the server's job.** The client echoes it
+  byte-exact and never inspects it; the server MUST treat it as
+  attacker-controlled. The SDK ships no signing helper yet.
 
 ## Spec
 
-[Multi-round tool results — server features](https://modelcontextprotocol.io/specification/draft/server/tools#multi-round-results)
-
-## Working example elsewhere
-
-The TypeScript SDK ships a runnable `mrtr` story:
-[typescript-sdk/examples/mrtr](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/mrtr).
+[Multi-round results — server features](https://modelcontextprotocol.io/specification/draft/server/tools#multi-round-results)
 
 ## See also
 
-`legacy_elicitation/` and `sampling/` — the handshake-era push equivalents that
-this mechanism replaces on the 2026 protocol. The TypeScript SDK ships a single
-dual-era `elicitation/` story covering both eras in one place; we re-merge
-`legacy_elicitation/` back into `elicitation/` once MRTR lands.
+`legacy_elicitation/` and `sampling/` — the handshake-era push equivalents this
+mechanism replaces on the 2026 protocol.

examples/stories/mrtr/__init__.py

@@ -0,0 +1,46 @@
+"""Drive the deploy tool both ways: the Client auto-loop, and a manual session-level loop."""
+
+import mcp_types as types
+
+from mcp.client import Client, ClientRequestContext
+from stories._harness import Target, run_client
+
+
+async def on_elicit(context: ClientRequestContext, params: types.ElicitRequestParams) -> types.ElicitResult:
+    # The same callback serves legacy push-style elicitation/create requests AND embedded
+    # InputRequiredResult.input_requests entries — the driver dispatches both here.
+    assert isinstance(params, types.ElicitRequestFormParams)
+    assert "confirm" in params.requested_schema["properties"]
+    return types.ElicitResult(action="accept", content={"confirm": True})
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    async with Client(target, mode=mode, elicitation_callback=on_elicit) as client:
+        # ── auto-loop: Client.call_tool dispatches input_requests to on_elicit and retries
+        # internally; the caller just sees the final CallToolResult.
+        deployed = await client.call_tool("deploy", {"env": "production"})
+        assert isinstance(deployed.content[0], types.TextContent)
+        assert deployed.content[0].text == "deployed to production", deployed
+
+        # ── manual loop: drop to client.session for the raw InputRequiredResult so the
+        # request_state can be persisted between rounds (e.g. across a process restart).
+        first = await client.session.call_tool("deploy", {"env": "staging"}, allow_input_required=True)
+        assert isinstance(first, types.InputRequiredResult)
+        assert first.input_requests is not None and "confirm" in first.input_requests
+        assert first.request_state == "awaiting-confirm"
+        # Decline this time so the path diverges from the auto-loop run above.
+        responses: types.InputResponses = {"confirm": types.ElicitResult(action="decline")}
+        second = await client.session.call_tool(
+            "deploy",
+            {"env": "staging"},
+            input_responses=responses,
+            request_state=first.request_state,
+            allow_input_required=True,
+        )
+        assert isinstance(second, types.CallToolResult)
+        assert isinstance(second.content[0], types.TextContent)
+        assert second.content[0].text == "deployment to staging cancelled", second
+
+
+if __name__ == "__main__":
+    run_client(main)