Multi Round-Trip Requests (MRTR)

[halter73]

Summary

Implements SEP-2322: Multi Round-Trip Requests (MRTR) for the C# SDK.

MRTR lets a server tool ask the client for input — elicitation, sampling, or roots — as part of a single tool call by returning an incomplete result instead of a final one. The client resolves the input requests and retries the original tools/call with inputResponses attached, until the tool returns a final result.

This PR follows the ratified draft wire format and gates the new behavior on the negotiated protocol revision DRAFT-2026-v1. There are no experimental opt-in flags.

The API

InputRequiredException is the only way to do MRTR. A tool throws it with an InputRequiredResult containing inputRequests and/or requestState, and the SDK turns that into the right wire response for the negotiated protocol.

[McpServerTool]
public static string Ask(McpServer server, RequestContext<CallToolRequestParams> context, string question)
{
    if (context.Params!.InputResponses?["answer"].ElicitationResult is { } answered)
        return $"You said: {answered.Content?.FirstOrDefault().Value}";

    if (!server.IsMrtrSupported)
        return "MRTR is not supported by this client.";

    throw new InputRequiredException(
        inputRequests: new Dictionary<string, InputRequest>
        {
            ["answer"] = InputRequest.ForElicitation(new ElicitRequestParams { Message = question, RequestedSchema = new() }),
        },
        requestState: "awaiting");
}

McpServer.IsMrtrSupported returns true whenever the SDK can satisfy InputRequiredException — either natively (draft) or via the legacy resolver (current+stateful).

Compatibility matrix

Negotiated protocol	Session	Behavior
DRAFT-2026-v1	Stateful / Stateless	Native — InputRequiredResult is serialized straight to the wire.
Current (2025-06-18 and earlier)	Stateful	Backcompat resolver — SDK sends standard elicitation/create / sampling/createMessage / roots/list requests, collects responses, retries the handler with inputResponses. Capped at 10 rounds.
Current	Stateless	Not supported — InputRequiredException raises an McpException.

Breaking changes under DRAFT-2026-v1

The draft revision removes the server-to-client elicitation/create, sampling/createMessage, and roots/list request methods. The SDK fails fast:

• McpServer.ElicitAsync, SampleAsync, RequestRootsAsync, AsSamplingChatClient, ElicitAsTaskAsync, SampleAsTaskAsync all throw InvalidOperationException after a DRAFT-2026-v1 session is negotiated. The exception message points to the InputRequest.ForElicitation / ForSampling / ForRootsList replacement.
• These methods continue to work normally under the current protocol revision and remain the recommended way to do simple one-shot client interactions.

Removed

• The implicit MRTR machinery that intercepted high-level ElicitAsync/SampleAsync calls and suspended the handler across MRTR rounds. (Replaced by the explicit InputRequiredException contract.)
• DeferTaskCreation on [McpServerTool] / McpServerToolCreateOptions and the server-side CreateTaskAsync API tied to it. Long-running tasks still use IMcpTaskStore as before.
• The ExperimentalProtocolVersion opt-in — replaced by negotiating DRAFT-2026-v1 directly.

Follow-ups (intentionally left out of this PR)

• The next protocol revision removes Mcp-Session-Id and the Stateful mode. When that lands, the current-protocol-stateful row of the matrix collapses into the stateless row, and the legacy elicitation/create / sampling/createMessage / roots/list resolver path can be deleted. The code has // TODO(stateless-draft): markers where that simplification will go.
• Conformance scenarios for SEP-2322 are wired up in tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests and gated on NodeHelpers.HasMrtrScenarios(). Once conformance#188 merges, the gate can be removed.

Tests

• ModelContextProtocol.Tests: 1980 passed, 0 failed, 4 skipped
• ModelContextProtocol.AspNetCore.Tests: 410 passed, 0 failed, 33 skipped

Includes new coverage:

• DraftProtocolGuardTests — verifies the legacy methods throw under DRAFT-2026-v1.
• MrtrLowLevelApiTests, MrtrSerializationTests — exercise InputRequiredException and its wire format.
• MapMcpTests.Mrtr — end-to-end Streamable HTTP coverage.
• SEP-2322 conformance scenarios under ServerConformanceTests (8 ephemeral + 3 task-based deferred).

Docs

• docs/concepts/mrtr/mrtr.md rewritten around InputRequiredException with the new compatibility matrix.
• docs/concepts/elicitation/, sampling/, roots/ updated to call out the DRAFT-2026-v1 behavior change.
• docs/concepts/tasks/tasks.md — DeferTaskCreation section removed.

[tarekgh]

In the input-requests branch, requestState is only set when the new InputRequiredResult carries one, but it's never removed from the cloned params. If an earlier round returned a requestState and a later round returns input requests without one, the stale value survives the DeepClone() and gets echoed back to the server. That breaks the opaque-state echo semantics: the client should echo the state from the current incomplete result, not an older one the server no longer emitted (and it can keep replaying state the server intended to drop).

Note the asymmetry with the requestState-only branch just below, which explicitly calls paramsObj.Remove(""inputResponses""). This branch should mirror that:

Suggested change

	if (inputRequiredResult.RequestState is { } requestState)
	{
	paramsObj["requestState"] = requestState;
	}
	if (inputRequiredResult.RequestState is { } requestState)
	{
	paramsObj["requestState"] = requestState;
	}
	else
	{
	paramsObj.Remove("requestState");
	}

The server-side back-compat resolver in McpServerImpl.InvokeWithInputRequiredResultHandlingAsync (around lines 1219-1227) has the same pattern and needs the same fix. The existing multi-round test always supplies requestState on every round, so this transition isn't currently covered; worth adding a case that drops requestState mid-sequence.

[tarekgh]

LGTM, Thanks!

[PranavSenthilnathan]

The experimental tasks API and the new one in #1579 handle input required in different ways than this.

The experimental tasks code allows the user to call ElicitAsync (since it's still valid as part of that spec) in the middle of a server tool call execution, but it adds the task id to the request. It does this by having a task local context that carries around the current MCP task id of the executing request.

#1579 handles this somewhat similarly. It allows the server tool call execution to call ElicitAsync, but instead just updates the task state to an InputRequiredTask instead of sending the request to the client.

In both cases, we let the tool implementor to call elicit/sample/etc., but this PR introduces an InputRequiredException instead. I'm wondering if there's a benefit in doing it this way instead of the other. Having input requests surface as exceptions doesn't seem intuitive (to me at least).

[halter73]

The key difference between MRTR and elicitation via tasks is there's no ID for the SDK to key off of. When I first opened this PR as a draft in March, it was using the Mcp-Session-Id header to find the ElicitAsync, SampleAsync and RootsAsync continuations.

With this PR, if you do an ElicitAsync with the draft protocol version and the stdio transport, we do the magic InputRequiredResult translation and then continue after ElicitAsync with the ElicitResult(s) from the InputRequest(s).

However, in stateless Streamable HTTP, we would be forced to keep a global continuation dictionary to support ElicitAsync et al., which would still be per-process and cause problems with load balancing, surviving server restarts etc. It's better to force people writing Streamable HTTP MCP servers to manually handle the InputRequest(s) and RequestState themselves, so they can write truly stateless handlers that work even if the elicitation/sampling/roots results end up going to a different process.

[halter73]

Correction. This is how I intended things to be, but I had reverted it. I added this behavior back with ff6372a. Please take a look.

[tarekgh]

Unbounded _mrtrContinuations for abandoned stateful MRTR flows

The implicit stateful path parks an MrtrContinuation in _mrtrContinuations[correlationId] whenever a handler suspends, and only removes it on a matching retry (TryRemove(requestState)) or in DisposeAsync. There's no size cap and no idle timeout, so a stateful client that starts MRTR flows (ElicitAsync/SampleAsync/RequestRootsAsync) and never sends the retry leaves each continuation resident for the life of the session — a parked handler task plus the intentionally-never-disposed CancellationTokenSource and all captured state. That's client-controlled, unbounded growth on long-lived stateful sessions.

Note this is asymmetric with the other path: InvokeWithInputRequiredResultHandlingAsync is bounded by const int MaxRetries = 10, but that only works because it drives all rounds synchronously within a single request. The implicit path spans multiple requests with no equivalent guard.

MrtrSessionLimitTests shows an app can govern this via outgoing/incoming message filters, but it defaults to int.MaxValue (unlimited) — so out of the box the SDK enforces nothing.

Could we add a default safeguard here; e.g. a per-session cap on concurrent parked continuations (fail the suspend with an error past the limit), or an idle timeout that cancels via the existing handler CTS and evicts the entry? If the intent is to leave governance entirely to the application, that's a defensible choice, but it should be called out explicitly in the MRTR docs along with the filter-based mitigation pattern from MrtrSessionLimitTests.

[halter73]

I see this as no different than the way you can have unlimited McpSessionHandler._pendingRequests. It is possible to limit this at the application layer by just not making more requests if too many pile up. If we address it for this, I think we should do so for all pending requests in a follow up PR.

[tarekgh]

Doc says "Error level" but the logger is Debug

The summary states it "Logs unhandled exceptions at Error level," but MrtrHandlerError is declared Level = LogLevel.Debug. Debug looks like the right choice (the same exception still propagates to the request pipeline, so Error would double-report), so I'd just update the doc comment to match — replace "at Error level" with "at Debug level".

[PranavSenthilnathan]

non-English characters

[PranavSenthilnathan]

Tasks would similarly need their own exception to indicate that the SDK needs to emit a CreateTaskResult. It would be nice to have a union here, so the user and our code know all the valid return types that are supported. Since C# doesn't have unions yet, we could consider our own custom type. As long as we can implement the new IUnion interface on it once the union feature lands in C#, we should be able to get the benefits (e.g. exhaustiveness checking).

[halter73]

I think something like IUnion should be saved for a follow up. I'm hesitant to add a custom type for this when C# Unions are so close. I'd rather just support those when they arrive. I can see the argument for it if it allows us to get rid of the exception, but I think it can be handled as a follow up.