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.