Add MRTR sections to elicitation, sampling, and roots docs

halter73 · Copilot · halter73 · commit 5db241998b7c · 2026-03-21T07:46:41.000-07:00
Add high-level and low-level MRTR examples to each feature doc:
- elicitation.md: ElicitAsync (transparent) + IncompleteResultException
- sampling.md: SampleAsync (transparent) + IncompleteResultException
- roots.md: RequestRootsAsync (transparent) + IncompleteResultException

Fix missing entries in docs navigation:
- toc.yml: Add Sampling under Client Features
- index.md: Add Tasks and MRTR to Base Protocol table

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md
@@ -170,6 +170,82 @@ Here's an example implementation of how a console application might handle elici
 
 [!code-csharp[](samples/client/Program.cs?name=snippet_ElicitationHandler)]
 
+### Multi Round-Trip Requests (MRTR)
+
+When both the client and server opt in to the experimental [MRTR](xref:mrtr) protocol, elicitation requests are handled via incomplete result / retry instead of a direct JSON-RPC request. This is transparent — the existing `ElicitAsync` API works identically regardless of whether MRTR is active.
+
+#### High-level API
+
+No code changes are needed. `ElicitAsync` automatically uses MRTR when both sides have opted in, and falls back to legacy JSON-RPC requests otherwise:
+
+```csharp
+// This code works the same with or without MRTR — the SDK handles it transparently.
+var result = await server.ElicitAsync(new ElicitRequestParams
+{
+    Message = "Please confirm the action",
+    RequestedSchema = new()
+    {
+        Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+        {
+            ["confirm"] = new ElicitRequestParams.BooleanSchema
+            {
+                Description = "Confirm the action"
+            }
+        }
+    }
+}, cancellationToken);
+```
+
+#### Low-level API
+
+For stateless servers or scenarios requiring manual control, throw <xref:ModelContextProtocol.Protocol.IncompleteResultException> with an elicitation input request. On retry, read the client's response from <xref:ModelContextProtocol.Protocol.RequestParams.InputResponses>:
+
+```csharp
+[McpServerTool, Description("Tool that elicits via low-level MRTR")]
+public static string ElicitWithMrtr(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    // On retry, process the client's elicitation response
+    if (context.Params!.InputResponses?.TryGetValue("user_input", out var response) is true)
+    {
+        var elicitResult = response.ElicitationResult;
+        return elicitResult?.Action == "accept"
+            ? $"User accepted: {elicitResult.Content?.FirstOrDefault().Value}"
+            : "User declined.";
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "This tool requires MRTR support.";
+    }
+
+    // First call — request user input
+    throw new IncompleteResultException(
+        inputRequests: new Dictionary<string, InputRequest>
+        {
+            ["user_input"] = InputRequest.ForElicitation(new ElicitRequestParams
+            {
+                Message = "Please confirm the action",
+                RequestedSchema = new()
+                {
+                    Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
+                    {
+                        ["confirm"] = new ElicitRequestParams.BooleanSchema
+                        {
+                            Description = "Confirm the action"
+                        }
+                    }
+                }
+            })
+        },
+        requestState: "awaiting-confirmation");
+}
+```
+
+> [!TIP]
+> See [Multi Round-Trip Requests (MRTR)](xref:mrtr) for the full protocol details, including multiple round trips, concurrent input requests, and the compatibility matrix.
+
 ### URL Elicitation Required Error
 
 When a tool cannot proceed without first completing a URL-mode elicitation (for example, when third-party OAuth authorization is needed), and calling `ElicitAsync` is not practical (for example in <xref: ModelContextProtocol.AspNetCore.HttpServerTransportOptions.Stateless> is enabled disabling server-to-client requests), the server may throw a <xref:ModelContextProtocol.UrlElicitationRequiredException>. This is a specialized error (JSON-RPC error code `-32042`) that signals to the client that one or more URL-mode elicitations must be completed before the original request can be retried.
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -18,6 +18,8 @@ Install the SDK and build your first MCP client and server.
 | [Progress tracking](progress/progress.md) | Learn how to track progress for long-running operations through notification messages. |
 | [Cancellation](cancellation/cancellation.md) | Learn how to cancel in-flight MCP requests using cancellation tokens and notifications. |
 | [Pagination](pagination/pagination.md) | Learn how to use cursor-based pagination when listing tools, prompts, and resources. |
+| [Tasks](tasks/tasks.md) | Learn how to create and manage long-running tool call tasks. |
+| [Multi Round-Trip Requests (MRTR)](mrtr/mrtr.md) | Learn how servers request client input during tool execution using incomplete results and retries. |
 
 ### Client Features
 
diff --git a/docs/concepts/roots/roots.md b/docs/concepts/roots/roots.md
@@ -103,3 +103,55 @@ server.RegisterNotificationHandler(
         Console.WriteLine($"Roots updated. {result.Roots.Count} roots available.");
     });
 ```
+
+### Multi Round-Trip Requests (MRTR)
+
+When both the client and server opt in to the experimental [MRTR](xref:mrtr) protocol, root list requests are handled via incomplete result / retry instead of a direct JSON-RPC request. This is transparent — the existing `RequestRootsAsync` API works identically regardless of whether MRTR is active.
+
+#### High-level API
+
+No code changes are needed. `RequestRootsAsync` automatically uses MRTR when both sides have opted in:
+
+```csharp
+// This code works the same with or without MRTR — the SDK handles it transparently.
+var result = await server.RequestRootsAsync(new ListRootsRequestParams(), cancellationToken);
+foreach (var root in result.Roots)
+{
+    Console.WriteLine($"Root: {root.Name ?? root.Uri}");
+}
+```
+
+#### Low-level API
+
+For stateless servers or scenarios requiring manual control, throw <xref:ModelContextProtocol.Protocol.IncompleteResultException> with a roots input request. On retry, read the client's response from <xref:ModelContextProtocol.Protocol.RequestParams.InputResponses>:
+
+```csharp
+[McpServerTool, Description("Tool that requests roots via low-level MRTR")]
+public static string ListRootsWithMrtr(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    // On retry, process the client's roots response
+    if (context.Params!.InputResponses?.TryGetValue("get_roots", out var response) is true)
+    {
+        var roots = response.RootsResult?.Roots ?? [];
+        return $"Found {roots.Count} roots: {string.Join(", ", roots.Select(r => r.Uri))}";
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "This tool requires MRTR support.";
+    }
+
+    // First call — request the client's root list
+    throw new IncompleteResultException(
+        inputRequests: new Dictionary<string, InputRequest>
+        {
+            ["get_roots"] = InputRequest.ForRootsList(new ListRootsRequestParams())
+        },
+        requestState: "awaiting-roots");
+}
+```
+
+> [!TIP]
+> See [Multi Round-Trip Requests (MRTR)](xref:mrtr) for the full protocol details, including load shedding, multiple round trips, and the compatibility matrix.
diff --git a/docs/concepts/sampling/sampling.md b/docs/concepts/sampling/sampling.md
@@ -117,3 +117,76 @@ McpClientOptions options = new()
 ### Capability negotiation
 
 Sampling requires the client to advertise the `sampling` capability. This is handled automatically — when a <xref:ModelContextProtocol.Client.McpClientHandlers.SamplingHandler> is set, the client includes the sampling capability during initialization. The server can check whether the client supports sampling before calling <xref:ModelContextProtocol.Server.McpServer.SampleAsync*>; if sampling is not supported, the method throws <xref:System.InvalidOperationException>.
+
+### Multi Round-Trip Requests (MRTR)
+
+When both the client and server opt in to the experimental [MRTR](xref:mrtr) protocol, sampling requests are handled via incomplete result / retry instead of a direct JSON-RPC request. This is transparent — the existing `SampleAsync` and `AsSamplingChatClient` APIs work identically regardless of whether MRTR is active.
+
+#### High-level API
+
+No code changes are needed. `SampleAsync` and `AsSamplingChatClient` automatically use MRTR when both sides have opted in, and fall back to legacy JSON-RPC requests otherwise:
+
+```csharp
+// This code works the same with or without MRTR — the SDK handles it transparently.
+var result = await server.SampleAsync(
+    new CreateMessageRequestParams
+    {
+        Messages =
+        [
+            new SamplingMessage
+            {
+                Role = Role.User,
+                Content = [new TextContentBlock { Text = "Summarize the data" }]
+            }
+        ],
+        MaxTokens = 256,
+    },
+    cancellationToken);
+```
+
+#### Low-level API
+
+For stateless servers or scenarios requiring manual control, throw <xref:ModelContextProtocol.Protocol.IncompleteResultException> with a sampling input request. On retry, read the client's response from <xref:ModelContextProtocol.Protocol.RequestParams.InputResponses>:
+
+```csharp
+[McpServerTool, Description("Tool that samples via low-level MRTR")]
+public static string SampleWithMrtr(
+    McpServer server,
+    RequestContext<CallToolRequestParams> context)
+{
+    // On retry, process the client's sampling response
+    if (context.Params!.InputResponses?.TryGetValue("llm_call", out var response) is true)
+    {
+        var text = response.SamplingResult?.Content
+            .OfType<TextContentBlock>().FirstOrDefault()?.Text;
+        return $"LLM said: {text}";
+    }
+
+    if (!server.IsMrtrSupported)
+    {
+        return "This tool requires MRTR support.";
+    }
+
+    // First call — request LLM completion from the client
+    throw new IncompleteResultException(
+        inputRequests: new Dictionary<string, InputRequest>
+        {
+            ["llm_call"] = InputRequest.ForSampling(new CreateMessageRequestParams
+            {
+                Messages =
+                [
+                    new SamplingMessage
+                    {
+                        Role = Role.User,
+                        Content = [new TextContentBlock { Text = "Summarize the data" }]
+                    }
+                ],
+                MaxTokens = 256
+            })
+        },
+        requestState: "awaiting-sample");
+}
+```
+
+> [!TIP]
+> See [Multi Round-Trip Requests (MRTR)](xref:mrtr) for the full protocol details, including load shedding, multiple round trips, and the compatibility matrix.
diff --git a/docs/concepts/toc.yml b/docs/concepts/toc.yml
@@ -23,6 +23,8 @@ items:
     uid: mrtr
 - name: Client Features
   items:
+  - name: Sampling
+    uid: sampling
   - name: Roots
     uid: roots
   - name: Elicitation
