Implement SEP-2322: Multi Round-Trip Requests

[felixweinberger]

This is a tracking issue for implementation of SEP-2322.

[mattzcarey]

Status — SEP-2322 (Multi Round-Trip Requests / MRTR)

Track: A (core) — depends on #2186 (SEP-2260) and #2184/#2185 (Group A). The MRTR public API design is the biggest API change of the release and a designated all-hands review moment per the track plan.
Spec: seps/2322-MRTR.md · merged spec#2322 2026-05-06

What's done

• Nothing in main yet (no InputRequiredResult, no resultType, no client retry loop).
• Closed exploration:
  • feat(core): RequiresInput catch in Dispatcher.dispatch -> IncompleteResult; MRTR types (SEP-2322) #2062 (closed) — RequiresInput thrown by ctx.mcpReq.send; dispatcher catches → IncompleteResult; MRTR types
  • feat(client): MRTR retry loop, ClientTransport, version-gate notifications/initialized (SEP-2322/2575) #2065 (closed) — client retry loop on IncompleteResult; services inputRequests via local handlers; resends with params.{inputResponses, requestState}
  • feat(server): ContinuationCompat (SEP-2322 Option H suspend/resume) #2067 (closed) — ContinuationCompat (Option H suspend/resume): parks the live handler frame, resumes on the follow-up POST (TTL-bounded, principal-bound). Notable design: opt-in via shttpHandler({continuation: ...}).

Open PR stack

• [SEP-2575][SEP-2322][SEP-2567] 2026-06 stateless support over StreamableHTTP #2131 (open) — bundles SEP-2322 wire behavior over StreamableHTTP alongside 2575/2567.

Outstanding (acceptance criteria, summary)

• InputRequiredResult with resultType: "input_required" returned to MRTR-capable clients only
• inputRequests keys unique per request; values constrained to Elicit / CreateMessage / ListRoots types
• requestState opaque, byte-round-tripped, treated as attacker-controlled (integrity-protect when it influences authz/logic; reject failed verification)
• Retry JSON-RPC id MUST differ from original
• Server SHOULD re-prompt on incomplete inputResponses; SHOULD ignore unrecognized keys; SHOULD validate shape (malformed → JSON-RPC error)
• inputResponses / requestState MUST NOT be applied to other parallel client requests
• Client must bound retry rounds (maxRounds)
• Replay mitigation: embed + verify authenticated principal, TTL, originating-request id inside the integrity-protected requestState
• Capability-gated: server MUST NOT send inputRequests types the client doesn't support
• (Derived BC) legacy path uses SSE-push or capability error, not InputRequiredResult
• Servers MUST send s→c requests via MRTR pattern; the server-initiated push pattern is no longer supported (overlap with Implement SEP-2260: Require Server requests to be associated with a Client request #2186)

Post-85ec3771 clarifications to fold in

• spec#2725 — MRTR bug & doc fixes
• spec#2773 — explicitly support extending ResultType

Public-API decision points (call them out for the review meeting)

1. Handler ergonomics: keep the existing await ctx.elicitInput() shape and translate it (Option H continuation) vs. surface MRTR explicitly with an InputRequest[] return.
2. Continuation storage seam: in-memory default vs. pluggable store, TTL knobs, multi-replica behavior.
3. Client retry policy: default maxRounds, backoff, idempotency considerations.

Coordination

Per the track plan: blocks #2189 (Tasks, which composes MRTR + Extensions). Coordinate with #2184 on RequestEnv / BaseContext.ext shape since MRTR types live alongside the per-request envelope.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For Multi Round-Trip Requests, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.