Add low-level MRTR server API and documentation

- Add IncompleteResultException for tool handlers to return incomplete
  results with inputRequests and/or requestState directly
- Add McpServer.IsMrtrSupported property for checking client compatibility
- Handle IncompleteResultException in MRTR wrapper and race handler
- Validate MRTR support when exception is thrown (returns JSON-RPC error
  if client doesn't support MRTR)
- Fall through to MRTR-aware invocation for unmatched requestState retries
- Add 8 protocol conformance tests (raw HTTP) for low-level MRTR flows
- Add 7 integration tests for client auto-retry of low-level tools
- Add MRTR concept documentation covering both high-level and low-level APIs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: halter73

docs/concepts/mrtr/mrtr.md

@@ -0,0 +1,343 @@
+---
+title: Multi Round-Trip Requests (MRTR)
+author: halter73
+description: How servers request client input during tool execution using Multi Round-Trip Requests.
+uid: mrtr
+---
+
+# Multi Round-Trip Requests (MRTR)
+
+<!-- mlc-disable-next-line -->
+> [!WARNING]
+> MRTR is an **experimental feature** based on a draft MCP specification proposal. The API may change in future releases. See the [Experimental APIs](../../experimental.md) documentation for details on working with experimental APIs. Both the client and server must opt in via <xref:ModelContextProtocol.Client.McpClientOptions.ExperimentalProtocolVersion> and <xref:ModelContextProtocol.Server.McpServerOptions.ExperimentalProtocolVersion> respectively.
+
+Multi Round-Trip Requests (MRTR) allow a server tool to request input from the client — such as [elicitation](xref:elicitation), [sampling](xref:sampling), or [roots](xref:roots) — as part of a single tool call, without requiring a separate JSON-RPC request for each interaction. Instead of sending a final result, the server returns an **incomplete result** containing one or more input requests. The client fulfills those requests and retries the original tool call with the responses attached.
+
+## Overview
+
+MRTR is useful when:
+
+- A tool needs user confirmation before proceeding (elicitation)
+- A tool needs LLM reasoning from the client (sampling)
+- A tool needs an updated list of client roots
+- A tool needs to perform multiple rounds of interaction in a single logical operation
+- A stateless server needs to orchestrate multi-step flows without keeping handler state in memory
+
+## How MRTR works
+
+1. The client calls a tool on the server via `tools/call`.
+2. The server tool determines it needs client input and returns an `IncompleteResult` containing `inputRequests` and/or `requestState`.
+3. The client resolves each input request (e.g., prompts the user for elicitation, calls an LLM for sampling).
+4. The client retries the original `tools/call` with `inputResponses` (keyed to the input requests) and `requestState` echoed back.
+5. The server processes the responses and either returns a final result or another `IncompleteResult` for additional rounds.
+
+## Opting in
+
+MRTR requires both the client and server to opt in by setting `ExperimentalProtocolVersion` to a draft protocol version. Currently, this is `"2026-06-XX"`:
+
+```csharp
+// Server
+var builder = Host.CreateApplicationBuilder();
+builder.Services.AddMcpServer(options =>
+{
+    options.ExperimentalProtocolVersion = "2026-06-XX";
+})
+.WithTools<MyTools>();
+```
+
+```csharp
+// Client
+var options = new McpClientOptions
+{
+    ExperimentalProtocolVersion = "2026-06-XX",
+    Handlers = new McpClientHandlers
+    {
+        ElicitationHandler = HandleElicitationAsync,
+        SamplingHandler = HandleSamplingAsync,
+    }
+};
+```
+
+When both sides opt in, the negotiated protocol version activates MRTR. When either side does not opt in, the SDK gracefully falls back to standard behavior.
+
+## High-level API
+
+The high-level API lets tool handlers call <xref:ModelContextProtocol.Server.McpServer.ElicitAsync*> and <xref:ModelContextProtocol.Server.McpServer.SampleAsync*> as if they were simple async calls. The SDK transparently manages the incomplete result / retry cycle.
+
+```csharp
+[McpServerToolType]
+public class InteractiveTools
+{
+    [McpServerTool, Description("Asks the user for confirmation before proceeding")]
+    public static async Task<string> ConfirmAction(
+        McpServer server,
+        [Description("The action to confirm")] string action,
+        CancellationToken cancellationToken)
+    {
+        var result = await server.ElicitAsync(new ElicitRequestParams
+        {
+            Message = $"Do you want to proceed with: {action}?",
+            RequestedSchema = new()
+            {
+                Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+                {
+                    ["confirm"] = new ElicitRequestParams.BooleanSchema
+                    {
+                        Description = "Confirm the action"
+                    }
+                }
+            }
+        }, cancellationToken);
+
+        return result.Action == "accept" ? "Action confirmed!" : "Action cancelled.";
+    }
+}
+```
+
+From the client's perspective, this is a single `CallToolAsync` call. The SDK handles all retries automatically:
+
+```csharp
+var result = await client.CallToolAsync("ConfirmAction", new { action = "delete all files" });
+Console.WriteLine(result.Content.OfType<TextContentBlock>().First().Text);
+```
+
+> [!TIP]
+> The high-level API requires session affinity — the handler task stays suspended in server memory between round trips. This works well for stateful (non-stateless) server configurations.
+
+## Low-level API
+
+The low-level API gives tool handlers direct control over `inputRequests` and `requestState`. This enables stateless multi-round-trip flows where the server does not need to keep handler state in memory between retries.
+
+### Checking MRTR support
+
+Before using the low-level API, check <xref:ModelContextProtocol.Server.McpServer.IsMrtrSupported> to determine if the connected client supports MRTR. If it does not, provide a fallback experience:
+
+```csharp
+[McpServerTool, Description("A tool that uses low-level MRTR")]
+public static string MyTool(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    if (!server.IsMrtrSupported)
+    {
+        return "This tool requires a client that supports multi-round-trip requests. "
+             + "Please upgrade your client or enable experimental protocol support.";
+    }
+
+    // ... MRTR logic
+}
+```
+
+### Returning an incomplete result
+
+Throw <xref:ModelContextProtocol.Protocol.IncompleteResultException> to return an incomplete result to the client. The exception carries an <xref:ModelContextProtocol.Protocol.IncompleteResult> containing `inputRequests` and/or `requestState`:
+
+```csharp
+[McpServerTool, Description("Stateless tool managing its own MRTR flow")]
+public static string StatelessTool(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context,
+    [Description("The user's question")] string question)
+{
+    var requestState = context.Params!.RequestState;
+    var inputResponses = context.Params!.InputResponses;
+
+    // On retry, process the client's responses
+    if (requestState is not null && inputResponses is not null)
+    {
+        var elicitResult = inputResponses["user_answer"].ElicitationResult;
+        return $"You answered: {elicitResult?.Content?.FirstOrDefault().Value}";
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "MRTR is not supported by this client.";
+    }
+
+    // First call — request user input
+    throw new IncompleteResultException(
+        inputRequests: new Dictionary<string, InputRequest>
+        {
+            ["user_answer"] = InputRequest.ForElicitation(new ElicitRequestParams
+            {
+                Message = $"Please answer: {question}",
+                RequestedSchema = new()
+                {
+                    Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+                    {
+                        ["answer"] = new ElicitRequestParams.StringSchema
+                        {
+                            Description = "Your answer"
+                        }
+                    }
+                }
+            })
+        },
+        requestState: "awaiting-answer");
+}
+```
+
+### Accessing retry data
+
+When the client retries a tool call, the retry data is available on the request parameters:
+
+- <xref:ModelContextProtocol.Protocol.RequestParams.InputResponses> — a dictionary of client responses keyed by the same keys used in `inputRequests`
+- <xref:ModelContextProtocol.Protocol.RequestParams.RequestState> — the opaque state string echoed back by the client
+
+Each `InputResponse` has typed accessors for the response type:
+
+- `ElicitationResult` — the result of an elicitation request
+- `SamplingResult` — the result of a sampling request
+- `RootsResult` — the result of a roots list request
+
+### Load shedding with requestState-only responses
+
+A server can return a `requestState`-only incomplete result (without any `inputRequests`) to defer processing. This is useful for load shedding or breaking up long-running work across multiple requests:
+
+```csharp
+[McpServerTool, Description("Tool that defers work using requestState")]
+public static string DeferredTool(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    var requestState = context.Params!.RequestState;
+
+    if (requestState is not null)
+    {
+        // Resume deferred work
+        var state = JsonSerializer.Deserialize<MyState>(
+            Convert.FromBase64String(requestState));
+        return $"Completed step {state!.Step}";
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "MRTR is not supported by this client.";
+    }
+
+    // Defer work to a later retry
+    var initialState = new MyState { Step = 1 };
+    throw new IncompleteResultException(
+        requestState: Convert.ToBase64String(
+            JsonSerializer.SerializeToUtf8Bytes(initialState)));
+}
+```
+
+The client automatically retries `requestState`-only incomplete results, echoing the state back without needing to resolve any input requests.
+
+### Multiple round trips
+
+A tool can perform multiple rounds of interaction by throwing `IncompleteResultException` multiple times across retries:
+
+```csharp
+[McpServerTool, Description("Multi-step wizard")]
+public static string WizardTool(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    var requestState = context.Params!.RequestState;
+    var inputResponses = context.Params!.InputResponses;
+
+    if (requestState == "step-2" && inputResponses is not null)
+    {
+        var name = inputResponses["name"].ElicitationResult?.Content?.FirstOrDefault().Value;
+        var age = inputResponses["age"].ElicitationResult?.Content?.FirstOrDefault().Value;
+        return $"Welcome, {name}! You are {age} years old.";
+    }
+
+    if (requestState == "step-1" && inputResponses is not null)
+    {
+        var name = inputResponses["name"].ElicitationResult?.Content?.FirstOrDefault().Value;
+
+        // Second round — ask for age
+        throw new IncompleteResultException(
+            inputRequests: new Dictionary<string, InputRequest>
+            {
+                ["age"] = InputRequest.ForElicitation(new ElicitRequestParams
+                {
+                    Message = $"Hi {name}! How old are you?",
+                    RequestedSchema = new()
+                    {
+                        Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+                        {
+                            ["age"] = new ElicitRequestParams.NumberSchema
+                            {
+                                Description = "Your age"
+                            }
+                        }
+                    }
+                })
+            },
+            requestState: "step-2");
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "MRTR is not supported. Please use a compatible client.";
+    }
+
+    // First round — ask for name
+    throw new IncompleteResultException(
+        inputRequests: new Dictionary<string, InputRequest>
+        {
+            ["name"] = InputRequest.ForElicitation(new ElicitRequestParams
+            {
+                Message = "What's your name?",
+                RequestedSchema = new()
+                {
+                    Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+                    {
+                        ["name"] = new ElicitRequestParams.StringSchema
+                        {
+                            Description = "Your name"
+                        }
+                    }
+                }
+            })
+        },
+        requestState: "step-1");
+}
+```
+
+### Providing custom error messages
+
+When MRTR is not supported, you can provide domain-specific guidance:
+
+```csharp
+if (!server.IsMrtrSupported)
+{
+    return "This tool requires interactive input, but your client doesn't support "
+         + "multi-round-trip requests. To use this feature:\n"
+         + "1. Update to a client that supports MCP protocol version 2026-06-XX or later\n"
+         + "2. Enable the experimental protocol version in your client configuration\n"
+         + "\nFor more information, see: https://example.com/mrtr-setup";
+}
+```
+
+## Compatibility
+
+The SDK handles all four combinations of experimental/non-experimental client and server:
+
+| Server Experimental | Client Experimental | Behavior |
+|---|---|---|
+| ✅ | ✅ | MRTR — incomplete results with retry cycle |
+| ✅ | ❌ | Server falls back to legacy JSON-RPC requests for elicitation/sampling |
+| ❌ | ✅ | Client accepts stable protocol version; MRTR retry loop is a no-op |
+| ❌ | ❌ | Standard behavior — no MRTR |
+
+When a server has MRTR enabled but the connected client does not:
+
+- The high-level API (`ElicitAsync`, `SampleAsync`) automatically falls back to sending standard JSON-RPC requests — no code changes needed.
+- The low-level API reports `IsMrtrSupported == false`, allowing the tool to provide a custom fallback message.
+- Throwing `IncompleteResultException` when MRTR is not supported results in a JSON-RPC error being returned to the client.
+
+## Choosing between high-level and low-level APIs
+
+| Consideration | High-level API | Low-level API |
+|---|---|---|
+| **Session affinity** | Required — handler stays suspended in memory | Not required — handler completes each round |
+| **State management** | Automatic (SDK manages via `MrtrContext`) | Manual (`requestState` encoded by you) |
+| **Complexity** | Simple `await` calls | More code, but full control |
+| **Stateless servers** | Not compatible | Designed for stateless scenarios |
+| **Fallback** | Automatic — SDK sends legacy requests | Manual — check `IsMrtrSupported` |
+| **Multiple input types** | One at a time (elicit or sample) | Multiple in a single round |

docs/concepts/toc.yml

@@ -19,6 +19,8 @@ items:
     uid: pagination
   - name: Tasks
     uid: tasks
+  - name: Multi Round-Trip Requests (MRTR)
+    uid: mrtr
 - name: Client Features
   items:
   - name: Roots