Add deferred task creation docs, revert MrtrContext to dictionary flow, fix logging

Document DeferTaskCreation and CreateTaskAsync in MRTR and Tasks
conceptual docs with cross-references and matching test coverage.

Revert MrtrContext flow from JsonRpcMessageContext property back to
_mrtrContextsByRequestId ConcurrentDictionary with try/finally.

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

Author: halter73

docs/concepts/mrtr/mrtr.md

@@ -331,6 +331,89 @@ When a server has MRTR enabled but the connected client does not:
 - 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.
 
+## Transitioning from MRTR to Tasks
+
+<!-- mlc-disable-next-line -->
+> [!WARNING]
+> Deferred task creation depends on both the [MRTR](xref:mrtr) and [Tasks](xref:tasks) experimental features.
+
+Some tools need user input before they can decide whether to start a long-running background task. For example, a VM provisioning tool might confirm costs with the user before committing to a task that takes minutes. **Deferred task creation** lets a tool perform ephemeral MRTR exchanges first, then transition to a background task only when ready.
+
+### How it works
+
+1. The tool sets `DeferTaskCreation = true` on its attribute or options.
+2. When the client sends task metadata with the `tools/call` request, the SDK runs the tool through the normal MRTR-wrapped path instead of creating a task immediately.
+3. The tool calls `ElicitAsync` or `SampleAsync` as usual — these use MRTR (incomplete result / retry cycles).
+4. When the tool is ready, it calls `await server.CreateTaskAsync(cancellationToken)` to transition to a background task.
+5. After `CreateTaskAsync`, the MRTR phase ends. Any subsequent `ElicitAsync` or `SampleAsync` calls use the task's own `input_required` / `tasks/input_response` mechanism instead.
+6. If the tool returns without calling `CreateTaskAsync`, a normal (non-task) result is sent to the client.
+
+### Server example
+
+```csharp
+McpServerTool.Create(
+    async (string vmName, McpServer server, CancellationToken ct) =>
+    {
+        // Phase 1: Ephemeral MRTR — confirm with user before starting expensive work.
+        var confirmation = await server.ElicitAsync(new ElicitRequestParams
+        {
+            Message = $"Provision VM '{vmName}'? This will incur costs.",
+            RequestedSchema = new()
+        }, ct);
+
+        if (confirmation.Action != "confirm")
+        {
+            return "Cancelled by user.";
+        }
+
+        // Phase 2: Transition to a background task.
+        await server.CreateTaskAsync(ct);
+
+        // Phase 3: Background work — runs as a task, client polls for status.
+        await Task.Delay(TimeSpan.FromMinutes(5), ct);
+        return $"VM '{vmName}' provisioned successfully.";
+    },
+    new McpServerToolCreateOptions
+    {
+        Name = "provision-vm",
+        Description = "Provisions a VM with user confirmation",
+        DeferTaskCreation = true,
+        Execution = new ToolExecution { TaskSupport = ToolTaskSupport.Optional },
+    })
+```
+
+The attribute-based equivalent uses `DeferTaskCreation` on <xref:ModelContextProtocol.Server.McpServerToolAttribute>:
+
+```csharp
+[McpServerTool(DeferTaskCreation = true, TaskSupport = ToolTaskSupport.Optional)]
+[Description("Provisions a VM with user confirmation")]
+public static async Task<string> ProvisionVm(
+    string vmName, McpServer server, CancellationToken ct)
+{
+    var confirmation = await server.ElicitAsync(new ElicitRequestParams
+    {
+        Message = $"Provision VM '{vmName}'? This will incur costs.",
+        RequestedSchema = new()
+    }, ct);
+
+    if (confirmation.Action != "confirm")
+        return "Cancelled by user.";
+
+    await server.CreateTaskAsync(ct);
+
+    await Task.Delay(TimeSpan.FromMinutes(5), ct);
+    return $"VM '{vmName}' provisioned successfully.";
+}
+```
+
+### Key points
+
+- **One-way transition**: Once `CreateTaskAsync` is called, the tool cannot go back to ephemeral MRTR. All subsequent input requests use the task workflow.
+- **Optional task creation**: A `DeferTaskCreation` tool can return a normal result without ever calling `CreateTaskAsync`. The tool decides at runtime whether to create a task.
+- **No task metadata, no deferral**: If the client calls the tool without task metadata, the tool runs normally with MRTR — `DeferTaskCreation` has no effect.
+
+For more details on task configuration and lifecycle, see the [Tasks](xref:tasks) documentation.
+
 ## Choosing between high-level and low-level APIs
 
 | Consideration | High-level API | Low-level API |

docs/concepts/tasks/tasks.md

@@ -137,6 +137,58 @@ Task support levels:
 - `Optional` (default for async methods): Tool can be called with or without task augmentation
 - `Required`: Tool must be called with task augmentation
 
+### Deferred Task Creation with MRTR
+
+<!-- mlc-disable-next-line -->
+> [!WARNING]
+> Deferred task creation depends on both the [Tasks](xref:tasks) and [MRTR](xref:mrtr) experimental features.
+
+By default, when a client sends task metadata with a `tools/call` request, the SDK creates a task immediately and runs the tool in the background. **Deferred task creation** delays the task creation, letting the tool perform ephemeral [MRTR](xref:mrtr) exchanges first — for example, to confirm an action with the user or gather required parameters — before committing to a background task.
+
+To opt in, set `DeferTaskCreation = true` on the tool:
+
+```csharp
+McpServerTool.Create(
+    async (string vmName, McpServer server, CancellationToken ct) =>
+    {
+        // Ephemeral MRTR — uses incomplete result / retry cycle.
+        var confirmation = await server.ElicitAsync(new ElicitRequestParams
+        {
+            Message = $"Provision VM '{vmName}'? This will incur costs.",
+            RequestedSchema = new()
+        }, ct);
+
+        if (confirmation.Action != "confirm")
+        {
+            return "Cancelled by user.";
+        }
+
+        // Transition to a background task.
+        await server.CreateTaskAsync(ct);
+
+        // Background work — runs as a task, client polls for status.
+        await Task.Delay(TimeSpan.FromMinutes(5), ct);
+        return $"VM '{vmName}' provisioned successfully.";
+    },
+    new McpServerToolCreateOptions
+    {
+        Name = "provision-vm",
+        Description = "Provisions a VM with user confirmation",
+        DeferTaskCreation = true,
+        Execution = new ToolExecution { TaskSupport = ToolTaskSupport.Optional },
+    })
+```
+
+After <xref:ModelContextProtocol.Server.McpServer.CreateTaskAsync*> returns:
+
+- The MRTR phase ends. The client receives a `CreateTaskResult` with the `taskId`.
+- Any subsequent `ElicitAsync` or `SampleAsync` calls in the handler use the task's `input_required` / `tasks/input_response` workflow instead of MRTR.
+- The handler's cancellation token is re-linked to the task's lifecycle (TTL expiration, explicit `tasks/cancel`).
+
+If the tool returns without calling `CreateTaskAsync`, a normal (non-task) result is sent to the client — no task is created.
+
+For more details on the MRTR mechanism and the transition flow, see [Transitioning from MRTR to Tasks](xref:mrtr#transitioning-from-mrtr-to-tasks).
+
 ### Explicit Task Creation with `IMcpTaskStore`
 
 For more control over task lifecycle, tools can directly interact with <xref:ModelContextProtocol.IMcpTaskStore> and return an `McpTask`. This approach allows you to:

src/ModelContextProtocol.Core/Protocol/JsonRpcMessageContext.cs

@@ -85,14 +85,4 @@ public sealed class JsonRpcMessageContext
     /// to flow the protocol version header so the server can determine client capabilities.
     /// </remarks>
     public string? ProtocolVersion { get; set; }
-
-    /// <summary>
-    /// Gets or sets the MRTR context for this request, if any.
-    /// </summary>
-    /// <remarks>
-    /// Set by <see cref="McpServer"/> when an MRTR-aware handler invocation is in progress,
-    /// so that the per-request <see cref="DestinationBoundMcpServer"/> can intercept
-    /// server-to-client requests (e.g. ElicitAsync, SampleAsync) and route them through the MRTR mechanism.
-    /// </remarks>
-    internal MrtrContext? MrtrContext { get; set; }
 }

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -30,6 +30,7 @@ internal sealed partial class McpServerImpl : McpServer
     private readonly SemaphoreSlim _disposeLock = new(1, 1);
     private readonly McpTaskCancellationTokenProvider? _taskCancellationTokenProvider;
     private readonly ConcurrentDictionary<string, MrtrContinuation> _mrtrContinuations = new();
+    private readonly ConcurrentDictionary<RequestId, MrtrContext> _mrtrContextsByRequestId = new();
 
     // Track MRTR handler tasks using the same inFlightCount + TCS pattern as
     // McpSessionHandler.ProcessMessagesCoreAsync. Starts at 1 for DisposeAsync itself.
@@ -822,11 +823,13 @@ await originalListToolsHandler(request, cancellationToken).ConfigureAwait(false)
                 }
                 catch (Exception e)
                 {
-                    // Skip logging for OperationCanceledException during server disposal —
-                    // MRTR handler cancellation during session teardown is expected, not an error.
+                    // Skip logging for OperationCanceledException when the cancellation token
+                    // is signaled — tool handler cancellation is an expected lifecycle event
+                    // (client request cancellation, session shutdown, MRTR teardown), not a
+                    // tool error.
                     // Skip logging for IncompleteResultException — it's normal MRTR control flow,
                     // not an error (the low-level API uses it to signal an IncompleteResult).
-                    if (!(e is OperationCanceledException && _disposed) && e is not IncompleteResultException)
+                    if (!(e is OperationCanceledException && cancellationToken.IsCancellationRequested) && e is not IncompleteResultException)
                     {
                         ToolCallError(request.Params?.Name ?? string.Empty, e);
                     }
@@ -1075,14 +1078,14 @@ async ValueTask<TResult> InvokeScopedAsync(
     }
 
     /// <summary>
-    /// Creates a per-request <see cref="DestinationBoundMcpServer"/> and attaches any
-    /// MRTR context that was set on the request by <see cref="WrapHandlerWithMrtr"/>.
+    /// Creates a per-request <see cref="DestinationBoundMcpServer"/> and attaches any pending
+    /// MRTR context that was stored by <see cref="WrapHandlerWithMrtr"/>.
     /// </summary>
     private DestinationBoundMcpServer CreateDestinationBoundServer(JsonRpcRequest jsonRpcRequest)
     {
         var server = new DestinationBoundMcpServer(this, jsonRpcRequest.Context?.RelatedTransport);
 
-        if (jsonRpcRequest.Context?.MrtrContext is { } mrtrContext)
+        if (_mrtrContextsByRequestId.TryRemove(jsonRpcRequest.Id, out var mrtrContext))
         {
             server.ActiveMrtrContext = mrtrContext;
         }
@@ -1288,10 +1291,19 @@ private void WrapHandlerWithMrtr(string method)
             // calling Cancel/Dispose inside locks or Interlocked guards.
             var handlerCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
 
-            // Flow the MrtrContext to the handler via the request's Context, where
-            // CreateDestinationBoundServer will pick it up to set on the per-request server.
-            (request.Context ??= new()).MrtrContext = mrtrContext;
-            var handlerTask = originalHandler(request, handlerCts.Token);
+            // Store the MrtrContext so CreateDestinationBoundServer can pick it up and set it
+            // on the per-request DestinationBoundMcpServer. This is picked up synchronously
+            // before any await, so the finally cleanup is safe.
+            _mrtrContextsByRequestId[request.Id] = mrtrContext;
+            Task<JsonNode?> handlerTask;
+            try
+            {
+                handlerTask = originalHandler(request, handlerCts.Token);
+            }
+            finally
+            {
+                _mrtrContextsByRequestId.TryRemove(request.Id, out _);
+            }
 
             // Wrap handler state into a continuation for lifecycle management across retries.
             var continuation = new MrtrContinuation(handlerCts, handlerTask, mrtrContext);

tests/ModelContextProtocol.Tests/Client/McpClientDeferredTaskCreationTests.cs

@@ -4,6 +4,7 @@
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using ModelContextProtocol.Tests.Utils;
+using System.ComponentModel;
 using System.Text.Json;
 
 namespace ModelContextProtocol.Tests.Client;
@@ -31,7 +32,8 @@ protected override void ConfigureServices(ServiceCollection services, IMcpServer
             options.ExperimentalProtocolVersion = "2026-06-XX";
         });
 
-        mcpServerBuilder.WithTools([
+        mcpServerBuilder.WithTools<DeferredTaskToolType>()
+        .WithTools([
             // Tool that elicits before creating a task, then does work in background.
             McpServerTool.Create(
                 async (string vmName, McpServer server, CancellationToken ct) =>
@@ -284,4 +286,49 @@ public async Task BackwardsCompat_ImmediateTaskCreation_WorksUnchanged()
         var taskStatus = await WaitForTaskCompletionAsync(result.Task.TaskId);
         Assert.Equal(McpTaskStatus.Completed, taskStatus.Status);
     }
+
+    [Fact]
+    public async Task DeferredTaskCreation_AttributeBased_ElicitThenCreateTask()
+    {
+        StartServer();
+        await using var client = await CreateMcpClientForServer(CreateClientOptions());
+
+        var result = await CallToolWithTaskMetadataAsync(client, "provision_vm",
+            new Dictionary<string, object?> { ["vmName"] = "test-vm" });
+
+        // The attribute-based tool should create a task after MRTR elicitation.
+        Assert.NotNull(result.Task);
+        Assert.NotEmpty(result.Task.TaskId);
+
+        var taskStatus = await WaitForTaskCompletionAsync(result.Task.TaskId);
+        Assert.Equal(McpTaskStatus.Completed, taskStatus.Status);
+    }
+
+    /// <summary>
+    /// Attribute-based tool type demonstrating deferred task creation.
+    /// Matches the pattern shown in the MRTR conceptual documentation.
+    /// </summary>
+    [McpServerToolType]
+    private sealed class DeferredTaskToolType
+    {
+        [McpServerTool(DeferTaskCreation = true, TaskSupport = ToolTaskSupport.Optional)]
+        [Description("Provisions a VM with user confirmation")]
+        public static async Task<string> ProvisionVm(
+            string vmName, McpServer server, CancellationToken ct)
+        {
+            var confirmation = await server.ElicitAsync(new ElicitRequestParams
+            {
+                Message = $"Provision VM '{vmName}'? This will incur costs.",
+                RequestedSchema = new()
+            }, ct);
+
+            if (confirmation.Action != "confirm")
+                return "Cancelled by user.";
+
+            await server.CreateTaskAsync(ct);
+
+            await Task.Delay(50, ct);
+            return $"VM '{vmName}' provisioned successfully.";
+        }
+    }
 }