Multi Round-Trip Requests (MRTR)

[halter73]

Spec PR: modelcontextprotocol/modelcontextprotocol#2322
Status: Draft — proof-of-concept reference implementation for SEP-2322

Summary

This PR implements Multi Round-Trip Requests (MRTR) in the C# MCP SDK, demonstrating that the SEP-2322 proposal can be implemented in a fully backwards-compatible way. The existing await-based server APIs (ElicitAsync, SampleAsync, RequestRootsAsync) continue to work identically — the SDK transparently handles the new wire protocol when both sides opt in, and falls back to legacy JSON-RPC requests when they don't.

This implementation is intended to serve as a reference for other SDK maintainers (TypeScript, Python, Go, Java) implementing MRTR, particularly around the backwards compatibility story and the interplay between protocol negotiation and handler behavior.

35 files changed, 4,725 lines added across 10 commits. ~2,200 lines of test coverage.

Motivation

As discussed in the Core Maintainer's meeting (accepted with changes, 🟢1 🟡7 🔴0), MRTR addresses fundamental scalability issues with the current server-to-client request model:

• Stateless servers can't send requests: SSE/stdio-based server→client requests require an open stream, which stateless HTTP servers don't have
• Load balancer incompatibility: Server-initiated requests over SSE can be routed to different server instances than the one that sent the request
• Simplified transport requirements: Clients no longer need to support bidirectional messaging for elicitation/sampling — standard HTTP request/response is sufficient

What This PR Demonstrates

1. Full Backwards Compatibility via Protocol Negotiation

This was the most debated topic in the spec PR (felixweinberger, maciej-kisiel, CaitieM20). The C# SDK proves all four combinations work seamlessly:

Server	Client	Behavior
Experimental	Experimental	MRTR — incomplete results with retry cycle
Experimental	Stable	Fallback — ElicitAsync/SampleAsync automatically send legacy JSON-RPC requests, as do IncompleteResultExceptions
Stable	Experimental	Client accepts stable protocol; MRTR retry loop is a no-op
Stable	Stable	Standard behavior — no MRTR, no changes

Key insight: The existing await server.ElicitAsync(...) API doesn't change at all. When the connected client supports MRTR, the SDK returns an IncompleteResult with inputRequests instead of sending a elicitation/create JSON-RPC request. When the client doesn't support MRTR, it sends the legacy request. Tool authors don't need to know or care which path is taken.

The determination is made via protocol version negotiation during initialize:

// Server-side check (McpServerImpl.cs)
internal bool ClientSupportsMrtr() =>
    _negotiatedProtocolVersion is not null &&
    _negotiatedProtocolVersion == ServerOptions.ExperimentalProtocolVersion;

This directly answers Randgalt's question — yes, the server knows the client supports MRTR purely from the negotiated protocol version. No new capabilities are needed.

2. Type Discrimination via result_type

This was flagged as a critical issue by maxisbey: since Result allows arbitrary extra fields, an IncompleteResult with only optional fields is indistinguishable from a CallToolResult. The spec resolved this with a result_type discriminator field.

The C# SDK implements this cleanly:

• Server side: IncompleteResult always serializes with "result_type": "incomplete"
• Client side: McpClientImpl.SendRequestAsync() checks for result_type == "incomplete" on every response, triggers the retry loop if found
• Default: When result_type is absent or any other value, the result deserializes as the expected type (backwards compatible)

This approach is extensible for future result types (tasks, callbacks, streaming) as CaitieM20 noted.

3. Two Server-Side API Levels

High-Level API (Stateful Servers)

Tool handlers use await — the SDK suspends the handler in memory and resumes it when the client retries with responses:

[McpServerTool, Description("Confirms an action with the user")]
public static async Task<string> ConfirmAction(McpServer server, string action, CancellationToken ct)
{
    // This call transparently uses MRTR or legacy JSON-RPC depending on the client
    var result = await server.ElicitAsync(new ElicitRequestParams
    {
        Message = $"Proceed with {action}?",
        RequestedSchema = new() { /* ... */ }
    }, ct);

    return result.Action == "accept" ? "Done!" : "Cancelled.";
}

Internally, the handler task is suspended via MrtrContext and stored in a ConcurrentDictionary<string, MrtrContinuation> keyed by a generated continuation ID. On retry, the continuation is looked up, the handler is resumed with the client's response, and execution continues from where ElicitAsync was awaited.

Low-Level API (Stateless Servers)

For servers that can't keep handler state in memory (stateless HTTP, serverless functions), handlers throw IncompleteResultException and manage their own state via requestState:

[McpServerTool, Description("Stateless tool with elicitation")]
public static string StatelessTool(McpServer server, RequestContext<CallToolRequestParams> context)
{
    // On retry, process the client's response
    if (context.Params!.InputResponses?.TryGetValue("user_input", out var response) is true)
    {
        return $"User said: {response.ElicitationResult?.Action}";
    }

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

    throw new IncompleteResultException(
        inputRequests: new Dictionary<string, InputRequest>
        {
            ["user_input"] = InputRequest.ForElicitation(new ElicitRequestParams { /* ... */ })
        },
        requestState: "awaiting-input");
}

The IncompleteResultException approach was chosen because C# doesn't yet have discriminated unions. However, C# unions are in active development, and when available, IncompleteResult return types will be a natural fit — returning either the final result or an IncompleteResult from a single method without exceptions. The exception-based API will remain supported but we expect the union-based approach to be preferred.

4. Client-Side Transparency

The client retry loop is fully automatic. CallToolAsync looks the same regardless of whether MRTR is active:

var result = await client.CallToolAsync("ConfirmAction", new { action = "deploy" });

Under the hood, McpClientImpl.SendRequestAsync detects result_type: "incomplete", resolves all inputRequests by dispatching to the registered handlers (ElicitationHandler, SamplingHandler, RootsHandler), and retries with inputResponses attached. Multiple input requests in a single IncompleteResult are resolved concurrently — all handler tasks are started immediately, then awaited.

The retry loop has a maximum of 10 attempts (not currently user-configurable). The escape hatch is CancellationToken.

5. Concurrent Multi-Input Resolution

A single IncompleteResult can request multiple types of input simultaneously:

throw new IncompleteResultException(
    inputRequests: new Dictionary<string, InputRequest>
    {
        ["confirm"] = InputRequest.ForElicitation(new ElicitRequestParams { /* ... */ }),
        ["summarize"] = InputRequest.ForSampling(new CreateMessageRequestParams { /* ... */ }),
        ["roots"] = InputRequest.ForRootsList(new ListRootsRequestParams())
    },
    requestState: "multi-input");

The client resolves all three concurrently and retries with all responses in one request. This is verified by tests using TaskCompletionSource barriers that prove all three handlers run simultaneously.

6. No Old-Style Requests with MRTR

When MRTR is negotiated, the server never sends elicitation/create, sampling/createMessage, or roots/list JSON-RPC requests. This is verified by message filter tests that inspect every outgoing message and confirm only IncompleteResult responses are used.

This is important for clients that can't support SSE streams (cloud-hosted clients) — MRTR means they can support elicitation and sampling via standard HTTP request/response.

7. MRTR-Native Backward Compatibility for the Low-Level API

Tools written with the low-level IncompleteResultException pattern work automatically with clients that don't support MRTR. When a tool throws IncompleteResultException and the client hasn't negotiated MRTR, the SDK resolves each InputRequest by sending the corresponding standard JSON-RPC call (elicitation, sampling, or roots) to the client, then retries the handler with the resolved responses — all internal to the server. The client never sees the IncompleteResult.

This mirrors the Python SDK's sse_retry_shim approach, but is built into the SDK rather than requiring an explicit wrapper. It means authors can write a single tool implementation using the MRTR-native pattern and it works with any client:

[McpServerTool, Description("Get weather with user's preferred units")]
public static string GetWeather(RequestContext<CallToolRequestParams> context, string location)
{
    if (context.Params!.InputResponses?.TryGetValue("units", out var response) == true)
    {
        var units = response.ElicitationResult?.Content?.FirstOrDefault().Value;
        return $"Weather for {location} in {units}: 72°";
    }

    throw new IncompleteResultException(
        inputRequests: new Dictionary<string, InputRequest>
        {
            ["units"] = InputRequest.ForElicitation(new ElicitRequestParams
            {
                Message = "Which temperature units?",
                RequestedSchema = new()
            })
        },
        requestState: "awaiting-units");
}

• MRTR client: IncompleteResult sent over the wire → client resolves and retries
• Non-MRTR client: SDK sends elicitation/create JSON-RPC to the client, collects the response, and retries the handler internally

The IsMrtrSupported check is no longer required for basic functionality — it remains useful for tools that want to provide a different experience when MRTR isn't available (e.g., a richer fallback message), but tools that just want elicitation/sampling can throw IncompleteResultException unconditionally.

New Protocol Types

Type	Description
IncompleteResult	Response with result_type: "incomplete", inputRequests, and/or requestState
IncompleteResultException	Exception thrown by low-level handlers to return an IncompleteResult
InputRequest	Server-to-client request wrapper with factory methods: ForElicitation(), ForSampling(), ForRootsList()
InputResponse	Client response wrapper with typed accessors: ElicitationResult, SamplingResult, RootsResult

All new types are marked [Experimental(MCPEXP001)] and gated behind ExperimentalProtocolVersion = "2026-06-XX".

RequestParams Extensions

All request parameter types (CallToolRequestParams, GetPromptRequestParams, ReadResourceRequestParams, etc.) inherit two new optional properties from RequestParams:

• InputResponses — Client's responses to the server's input requests, keyed by the same keys from inputRequests
• RequestState — Opaque string echoed back from the previous IncompleteResult

These are populated only on retries. On initial requests, both are null.

Test Coverage

~2,200 lines of tests across 8 test files covering:

• Protocol conformance: Full MRTR round-trip cycle, result_type discriminator, serialization/deserialization
• High-level API: ElicitAsync/SampleAsync with MRTR, automatic fallback to legacy
• Low-level API: IncompleteResultException, requestState management, multi-round trips
• Backwards compatibility: All 4 combinations of experimental/stable client and server, plus MRTR-native tools with non-MRTR clients
• Concurrent resolution: Multiple inputRequests in a single IncompleteResult, verified concurrent execution
• Stateless mode: Full end-to-end tests with Streamable HTTP in stateless mode
• Edge cases: Cancellation mid-retry, concurrent ElicitAsync/SampleAsync calls (prevented), message filter verification
• Tasks integration: MRTR with task-augmented tool calls

Documentation

• New: docs/concepts/mrtr/mrtr.md — comprehensive guide with high-level and low-level API examples, compatibility matrix, backward compatibility section
• Updated: elicitation.md, sampling.md, roots.md — each now includes an MRTR section showing both await-based and IncompleteResultException-based approaches
• Fixed: toc.yml and index.md navigation entries

Open Questions for the Spec

1. InputRequest method field: The spec's InputRequest type is a union of CreateMessageRequest | ElicitRequest | ListRootsRequest. In practice, the method field is needed for deserialization since the params shapes can overlap. The C# SDK uses InputRequest.Method as the discriminator for typed deserialization. The spec should be explicit that method is required.