Add deferred task creation with DeferTaskCreation + CreateTaskAsync

Add support for tools to perform ephemeral MRTR exchanges before
committing to a background task. This enables a two-phase workflow:

1. Ephemeral phase: The handler uses ElicitAsync/SampleAsync via MRTR
   to gather user input (e.g., confirmation before expensive operations).
2. Task phase: The handler calls CreateTaskAsync() to transition to a
   background task, receiving a task ID and cancellation token.

API surface:
- McpServerToolAttribute.DeferTaskCreation property
- McpServerToolCreateOptions.DeferTaskCreation property
- McpServerTool.DeferTaskCreation virtual property (overridden in
  AIFunctionMcpServerTool and DelegatingMcpServerTool)
- McpServer.CreateTaskAsync() virtual method (overridden in
  DestinationBoundMcpServer)

Implementation:
- DeferredTaskInfo carries task metadata across MRTR continuations,
  with signal/ack TCS pair for handler ↔ framework coordination.
- ConfigureTools attaches DeferredTaskInfo to MrtrContext when
  DeferTaskCreation is enabled and client provides task metadata.
- AwaitMrtrHandlerAsync races handler vs exchange vs task creation
  signal (3-way WhenAny).
- HandleDeferredTaskCreationAsync creates the task, re-links the
  handler CTS to the task cancellation token, and acknowledges the
  handler so it can continue as a background task.
- TrackDeferredHandlerTaskAsync tracks completion and stores results
  (handler already tracked by ObserveHandlerCompletionAsync for
  in-flight counting).

If the handler returns without calling CreateTaskAsync(), a normal
(non-task) result is returned to the client.

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

Author: halter73

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs

@@ -15,6 +15,7 @@ internal sealed partial class AIFunctionMcpServerTool : McpServerTool
 {
     private readonly bool _structuredOutputRequiresWrapping;
     private readonly IReadOnlyList<object> _metadata;
+    private readonly bool _deferTaskCreation;
 
     /// <summary>
     /// Creates an <see cref="McpServerTool"/> instance for a method, specified via a <see cref="Delegate"/> instance.
@@ -167,7 +168,7 @@ options.OpenWorld is not null ||
             tool.Execution.TaskSupport = ToolTaskSupport.Optional;
         }
 
-        return new AIFunctionMcpServerTool(function, tool, options?.Services, structuredOutputRequiresWrapping, options?.Metadata ?? []);
+        return new AIFunctionMcpServerTool(function, tool, options?.Services, structuredOutputRequiresWrapping, options?.Metadata ?? [], options?.DeferTaskCreation ?? false);
     }
 
     private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpServerToolCreateOptions? options)
@@ -211,6 +212,11 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
                 newOptions.Execution ??= new ToolExecution();
                 newOptions.Execution.TaskSupport ??= taskSupport;
             }
+
+            if (toolAttr._deferTaskCreation is bool deferTaskCreation)
+            {
+                newOptions.DeferTaskCreation = deferTaskCreation;
+            }
         }
 
         if (method.GetCustomAttribute<DescriptionAttribute>() is { } descAttr)
@@ -228,7 +234,7 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
     internal AIFunction AIFunction { get; }
 
     /// <summary>Initializes a new instance of the <see cref="McpServerTool"/> class.</summary>
-    private AIFunctionMcpServerTool(AIFunction function, Tool tool, IServiceProvider? serviceProvider, bool structuredOutputRequiresWrapping, IReadOnlyList<object> metadata)
+    private AIFunctionMcpServerTool(AIFunction function, Tool tool, IServiceProvider? serviceProvider, bool structuredOutputRequiresWrapping, IReadOnlyList<object> metadata, bool deferTaskCreation)
     {
         ValidateToolName(tool.Name);
 
@@ -237,11 +243,15 @@ private AIFunctionMcpServerTool(AIFunction function, Tool tool, IServiceProvider
 
         _structuredOutputRequiresWrapping = structuredOutputRequiresWrapping;
         _metadata = metadata;
+        _deferTaskCreation = deferTaskCreation;
     }
 
     /// <inheritdoc />
     public override Tool ProtocolTool { get; }
 
+    /// <inheritdoc />
+    public override bool DeferTaskCreation => _deferTaskCreation;
+
     /// <inheritdoc />
     public override IReadOnlyList<object> Metadata => _metadata;
 

src/ModelContextProtocol.Core/Server/DeferredTaskCreationResult.cs

@@ -0,0 +1,27 @@
+using ModelContextProtocol.Protocol;
+
+namespace ModelContextProtocol.Server;
+
+/// <summary>
+/// Contains the information the handler needs after the framework creates the deferred task.
+/// </summary>
+internal sealed class DeferredTaskCreationResult
+{
+    /// <summary>Gets the ID of the created task.</summary>
+    public required string TaskId { get; init; }
+
+    /// <summary>Gets the session ID associated with the task.</summary>
+    public required string? SessionId { get; init; }
+
+    /// <summary>Gets the task store for persisting task state.</summary>
+    public required IMcpTaskStore TaskStore { get; init; }
+
+    /// <summary>Gets whether to send task status notifications.</summary>
+    public required bool SendNotifications { get; init; }
+
+    /// <summary>Gets the function for sending task status notifications.</summary>
+    public required Func<McpTask, CancellationToken, Task>? NotifyTaskStatusFunc { get; init; }
+
+    /// <summary>Gets the cancellation token for the task (TTL-based or explicit).</summary>
+    public required CancellationToken TaskCancellationToken { get; init; }
+}

src/ModelContextProtocol.Core/Server/DeferredTaskInfo.cs

@@ -0,0 +1,78 @@
+using ModelContextProtocol.Protocol;
+
+namespace ModelContextProtocol.Server;
+
+/// <summary>
+/// Holds the state needed for deferred task creation, where a tool handler performs
+/// ephemeral MRTR exchanges before committing to a background task via
+/// <see cref="McpServer.CreateTaskAsync(CancellationToken)"/>.
+/// Stored on <see cref="MrtrContext.DeferredTask"/> and carried across MRTR continuations.
+/// </summary>
+internal sealed class DeferredTaskInfo
+{
+    /// <summary>Gets the task metadata from the original client request.</summary>
+    public required McpTaskMetadata TaskMetadata { get; init; }
+
+    /// <summary>Gets the JSON-RPC request ID of the current tools/call request.</summary>
+    public required RequestId OriginalRequestId { get; init; }
+
+    /// <summary>Gets the original JSON-RPC request.</summary>
+    public required JsonRpcRequest OriginalRequest { get; init; }
+
+    /// <summary>Gets the task store for persisting task state.</summary>
+    public required IMcpTaskStore TaskStore { get; init; }
+
+    /// <summary>Gets whether to send task status notifications.</summary>
+    public required bool SendNotifications { get; init; }
+
+    /// <summary>
+    /// Task that completes when the handler calls <see cref="McpServer.CreateTaskAsync(CancellationToken)"/>.
+    /// The framework races this against handler completion and MRTR exchanges.
+    /// </summary>
+    private readonly TaskCompletionSource<bool> _signalTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+    /// <summary>
+    /// TCS that the framework completes after creating the task, allowing the handler to continue.
+    /// </summary>
+    private readonly TaskCompletionSource<DeferredTaskCreationResult> _ackTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+    /// <summary>Gets the task that completes when the handler requests task creation.</summary>
+    public Task SignalTask => _signalTcs.Task;
+
+    /// <summary>
+    /// Called by the handler (via <see cref="McpServer.CreateTaskAsync(CancellationToken)"/>) to signal
+    /// the framework that a task should be created. Awaits the framework's acknowledgment.
+    /// </summary>
+    /// <returns>The result containing the created task's context information.</returns>
+    /// <exception cref="InvalidOperationException"><see cref="McpServer.CreateTaskAsync(CancellationToken)"/> was already called.</exception>
+    public async ValueTask<DeferredTaskCreationResult> RequestTaskCreationAsync(CancellationToken cancellationToken)
+    {
+        if (!_signalTcs.TrySetResult(true))
+        {
+            throw new InvalidOperationException("CreateTaskAsync has already been called for this tool execution.");
+        }
+
+        return await _ackTcs.Task.WaitAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Called by the framework after creating the task to unblock the handler.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Task creation was already acknowledged.</exception>
+    public void AcknowledgeTaskCreation(DeferredTaskCreationResult result)
+    {
+        if (!_ackTcs.TrySetResult(result))
+        {
+            throw new InvalidOperationException("Task creation was already acknowledged.");
+        }
+    }
+
+    /// <summary>
+    /// Called by the framework when task creation fails, propagating the exception
+    /// to the handler so <see cref="McpServer.CreateTaskAsync(CancellationToken)"/> throws.
+    /// </summary>
+    public void AcknowledgeFailure(Exception exception)
+    {
+        _ackTcs.TrySetException(exception);
+    }
+}

src/ModelContextProtocol.Core/Server/DelegatingMcpServerTool.cs

@@ -23,6 +23,9 @@ protected DelegatingMcpServerTool(McpServerTool innerTool)
     /// <inheritdoc />
     public override Tool ProtocolTool => _innerTool.ProtocolTool;
 
+    /// <inheritdoc />
+    public override bool DeferTaskCreation => _innerTool.DeferTaskCreation;
+
     /// <inheritdoc />
     public override IReadOnlyList<object> Metadata => _innerTool.Metadata;
 

src/ModelContextProtocol.Core/Server/DestinationBoundMcpServer.cs

@@ -89,4 +89,31 @@ private async Task<JsonRpcResponse> SendRequestViaMrtrAsync(
             Result = JsonSerializer.SerializeToNode(inputResponse.RawValue, McpJsonUtilities.JsonContext.Default.JsonElement),
         };
     }
+
+    /// <inheritdoc />
+    public override async ValueTask CreateTaskAsync(CancellationToken cancellationToken = default)
+    {
+        var deferredTask = ActiveMrtrContext?.DeferredTask
+            ?? throw new InvalidOperationException(
+                "CreateTaskAsync can only be called from a tool handler with DeferTaskCreation enabled " +
+                "when the client provides task metadata in the tools/call request.");
+
+        // Signal the framework to create the task and wait for acknowledgment.
+        // RequestTaskCreationAsync is atomic — throws if already called.
+        var result = await deferredTask.RequestTaskCreationAsync(cancellationToken).ConfigureAwait(false);
+
+        // Transition to task mode on the handler's async flow.
+        TaskExecutionContext.Current = new TaskExecutionContext
+        {
+            TaskId = result.TaskId,
+            SessionId = result.SessionId,
+            TaskStore = result.TaskStore,
+            SendNotifications = result.SendNotifications,
+            NotifyTaskStatusFunc = result.NotifyTaskStatusFunc,
+        };
+
+        // No more ephemeral MRTR — subsequent ElicitAsync/SampleAsync calls
+        // will go through SendRequestWithTaskStatusTrackingAsync instead.
+        ActiveMrtrContext = null;
+    }
 }

src/ModelContextProtocol.Core/Server/McpServer.cs

@@ -83,6 +83,40 @@ protected McpServer()
     [Experimental(Experimentals.Mrtr_DiagnosticId, UrlFormat = Experimentals.Mrtr_Url)]
     public virtual bool IsMrtrSupported => false;
 
+    /// <summary>
+    /// Transitions the current tool execution from ephemeral MRTR mode to a background task.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method is only valid when called from a tool handler that has
+    /// <see cref="McpServerToolAttribute.DeferTaskCreation"/> set to <see langword="true"/>
+    /// and the client provided task metadata in the <c>tools/call</c> request.
+    /// </para>
+    /// <para>
+    /// Before calling this method, <see cref="ElicitAsync(ElicitRequestParams, CancellationToken)"/>
+    /// and <see cref="SampleAsync(CreateMessageRequestParams, CancellationToken)"/> use the ephemeral
+    /// MRTR mechanism (returning <see cref="IncompleteResult"/> to the client). After calling this method,
+    /// the task is created and subsequent calls use the persistent workflow (task status
+    /// <see cref="McpTaskStatus.InputRequired"/> with <c>tasks/result</c> and <c>tasks/input_response</c>).
+    /// </para>
+    /// <para>
+    /// If the tool handler returns without calling this method, a normal (non-task) result is returned
+    /// to the client.
+    /// </para>
+    /// </remarks>
+    /// <param name="cancellationToken">A token to cancel the task creation.</param>
+    /// <exception cref="InvalidOperationException">
+    /// The tool does not have <see cref="McpServerToolAttribute.DeferTaskCreation"/> enabled, or
+    /// the client did not provide task metadata, or this method was already called.
+    /// </exception>
+    [Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
+    public virtual ValueTask CreateTaskAsync(CancellationToken cancellationToken = default)
+    {
+        throw new InvalidOperationException(
+            "CreateTaskAsync can only be called from a tool handler with DeferTaskCreation enabled " +
+            "when the client provides task metadata in the tools/call request.");
+    }
+
     /// <summary>
     /// Runs the server, listening for and handling client requests.
     /// </summary>