Implement SEP-2663 Tasks Extension

[PranavSenthilnathan]

Closes #1573

Implement SEP-2663 Tasks Extension

Re-implements the experimental MCP tasks extension to track SEP-2663, replacing the SEP-1686 implementation removed in cec5d99. Long-running tool invocations can now be offloaded to a background task that the client polls via tasks/get, with cooperative cancellation and multi-round-trip input requests.

Experimental — gated behind MCPEXP001.

Highlights

• Opt-in per request. A client adds the io.modelcontextprotocol/tasks key to a request''s _meta (under the SEP-2575 clientCapabilities.extensions envelope) to signal task support; the server must not return CreateTaskResult otherwise (enforced in McpServerImpl).
• Drop-in server config. Set McpServerOptions.TaskStore = new InMemoryMcpTaskStore() and every [McpServerTool] invocation is automatically wrapped, with tasks/get/tasks/update/tasks/cancel handlers wired from the store. Explicit handlers in McpServerOptions.Handlers override any slot.
• Transparent client polling. McpClient.CallToolAsync injects the extension marker, polls until terminal, dispatches input requests through the registered sampling/elicitation/roots handlers, and dedupes resolved keys across polls. CallToolRawAsync returns the raw ResultOrCreatedTask<T> for manual lifecycle management.
• Cooperative cancellation. tasks/cancel transitions the task in the store and signals a per-task CancellationTokenSource so the tool''s CancellationToken observes the cancel. Disposal races are resolved with TryRemove.
• Server-initiated requests inside a task. server.ElicitAsync/server.SampleAsync/server.RequestRootsAsync called from inside a tool scope are redirected through the store as input requests instead of direct JSON-RPC, surfaced to the client via InputRequiredTaskResult.InputRequests, and resumed via the store''s InputResponseReceived event when tasks/update arrives. Custom handlers can opt in via McpServer.CreateMcpTaskScope(taskId, store).

Public API surface

Protocol (ModelContextProtocol.Core/Protocol)

• CreateTaskResult, GetTaskResult (+ Working/InputRequired/Completed/Cancelled/Failed subtypes)
• UpdateTaskRequestParams/UpdateTaskResult, CancelTaskRequestParams/CancelTaskResult, GetTaskRequestParams
• TaskStatusNotificationParams (+ 5 subtypes — scaffolding for SEP-2575 push notifications)
• ResultOrCreatedTask<T> discriminator with implicit converters
• McpTaskStatus enum (snake_case wire values)
• McpExtensions.Tasks constant
• Result.ResultType discriminator ("task" / "complete")

Server (ModelContextProtocol.Core/Server)

• IMcpTaskStore + InMemoryMcpTaskStore (immutable record snapshots, lock-free CAS)
• McpTaskInfo, InputResponseReceivedEventArgs
• McpServerOptions.TaskStore
• McpServerHandlers.{CallToolWithTaskHandler, GetTaskHandler, UpdateTaskHandler, CancelTaskHandler} (CallToolHandler ⊥ CallToolWithTaskHandler mutual exclusion enforced at set time)
• McpServer.CreateMcpTaskScope(taskId, store)
• McpServer.SendTaskStatusNotificationAsync (polymorphic notification dispatch for notifications/tasks/*)

Client (ModelContextProtocol.Core/Client)

• McpClient.CallToolAsync (task-aware auto-polling)
• McpClient.CallToolRawAsync (no auto-polling)
• McpClient.GetTaskAsync / UpdateTaskAsync / CancelTaskAsync
• McpClientOptions.MaxConsecutiveStuckPolls (configures the stuck-task detector threshold; default 60)

Safety nets baked in

• Handler-set validation. Returning a CreateTaskResult without tasks/get wired throws InvalidOperationException at request time so misconfigured deployments fail loudly instead of producing unpollable tasks.
• Stuck-task detector. CallToolAsync gives up after a configurable number of consecutive InputRequired polls with no new input request keys (default 60, tunable via McpClientOptions.MaxConsecutiveStuckPolls), issues a best-effort tasks/cancel, and throws McpException so a misbehaving server can''t trap the client in an unbounded poll loop.
• Status semantics. Tools returning IsError = true produce Completed (per SEP) — Failed is reserved for JSON-RPC protocol errors, with the payload shaped as a JSON-RPC error object { code, message }.
• Capability bypass inside a task scope. Elicit/Sample/RequestRoots skip the negotiated-capability checks when called inside a task scope, since the tasks extension itself is the negotiated capability (the client opted in via _meta).

Tests

• 1953 ModelContextProtocol.Tests passing on .NET 10, 364 ModelContextProtocol.AspNetCore.Tests passing.
• New test files: McpServerTaskTests, McpTaskStoreTests, McpServerTasksNoStoreTests, InMemoryMcpTaskStoreTests, McpClientTaskMethodsTests, TaskSerializationTests, TaskCancellationIntegrationTests, TaskHandlerConfigurationValidationTests, TaskPollStuckDetectorTests, TaskStoreOrphanedTaskTests.
• Coverage includes wire-format round-trips for every GetTaskResult subtype, store CAS/idempotency, terminal-state transitions, isError → Completed mapping, capability bypass, mutual exclusion of CallToolHandler/CallToolWithTaskHandler, handler-set validation, stuck-detector cancellation flow with the configurable threshold, server→client notifications/tasks/* round-trip via SendTaskStatusNotificationAsync, roots/list redirection through the task store, no-store sync fallback when the client opts in but the server has none configured, and parity tests preserved/restored from the removed SEP-1686 implementation.

Sample

• samples/TasksExtension/ runs a server (configured with InMemoryMcpTaskStore) and a client over an in-memory pipe in a single process. Demonstrates both CallToolAsync (auto-poll) and CallToolRawAsync (manual GetTaskAsync loop with full GetTaskResult subtype handling).

Documentation

• Rewrote docs/concepts/tasks/tasks.md end-to-end: API examples, status/cancellation semantics, stuck-detector + configuration, custom store guidance (including strong-consistency requirements on CreateTaskAsync per SEP-2663 §306 and singleton-under-stateless-HTTP requirements), capability bypass, known limitations.
• Expanded XML docs on IMcpTaskStore, the three task lifecycle handlers, McpTaskExecutionContext, McpClientOptions.MaxConsecutiveStuckPolls, and the CallToolAsync(string, …) overload.

Known limitations (carried forward)

• Server-push task status notifications (SEP-2575) — SendTaskStatusNotificationAsync is plumbed end-to-end but auto-emission from the task wrapper is not wired yet; clients still rely on polling.
• Lazy task creation — CreateTaskAsync is invoked eagerly even for tools that return inline.
• Mid-execution promotion to task — [McpServerTool] methods can''t start sync and then escalate; use CallToolWithTaskHandler for that pattern.
• ServerCapabilities.Extensions source-gen round-trip remains lossy for arbitrary object payloads.

[halter73]

I had an agent take a careful pass against SEP-2663, SEP-2575, and the MRTR landing in #1458. Overall this is in great shape. The MRTR integration is clean, the typed input-request/response flow reads well, and the roots/list dispatch you added in this revision closes the gap from our earlier conversation.

Highlights from the inline comments, in priority order:

1. Wire-format _meta envelope (most important). SEP-2663 §51 / §58–62 says the per-request opt-in is the SEP-2575 envelope: _meta.io.modelcontextprotocol/clientCapabilities.extensions.io.modelcontextprotocol/tasks. We're currently writing and reading the bare _meta.io.modelcontextprotocol/tasks key on both sides, so two C# peers agree but a strictly-spec-shaped non-C# peer won't. Suggested change is symmetric on client (McpClient.Methods.cs) and server (McpServerImpl.cs); I'd also pair it with a small JSON-shape contract test (one that asserts the literal JSON path) so a future refactor can't silently regress to a bare key.
2. Failed payload structure + JsonDocument lifetime. Two real bugs in the same five-line catch block in McpServerImpl.cs: the failed payload only emits {"message": ...} (SEP-2663 §186 says it MUST be a JSON-RPC error object with at least code), and the JsonDocument.Parse(...).RootElement is never using-disposed so its pooled buffer can be recycled while the element is still in the store. Inline suggestion fixes both.
3. Roots/list tests. Production-side dispatch looks good — just needs a RootsTool fixture next to sample-tool and one RootsTool_ViaTask_RedirectsThroughStore test mirroring the existing sample/elicit pair. Inline suggestions provided.
4. Two related task-composition failure modes — both should fail loudly instead of silently. A CallToolWithTaskHandler that returns IsTask = true inside a TaskStore wrapper orphans the store's pre-created task (client polls a task that never completes); and an InputRequiredException thrown from a [McpServerTool] inside a task wrapper becomes a Failed task with a misleading message. Both fixes are a few lines — turn the orphan into a SetFailedAsync with a clear payload (Comment 5), and add a dedicated catch (InputRequiredException) that produces a "MRTR + tasks composition isn't supported under [McpServerTool] yet — use CallToolWithTaskHandler" error (Comment 9). I filed #1635 for the broader composability story as a follow-up.
5. IMcpTaskStore.CreateTaskAsync docs. SEP-2663 §306 imposes a strong-consistency requirement (tasks/get MUST resolve immediately after CreateTaskAsync returns). Worth adding a <remarks> paragraph so custom store implementers on eventually-consistent storage don't accidentally violate it.

Forward-compat notes from a parallel cross-check against #1610 (sessionless + handshake-less, SEP-2575/2567):

• IMcpTaskStore lifetime under stateless HTTP. Once #1610 lands and flips HTTP to Stateless = true by default, each POST spins up a fresh server instance. CallToolAsync → CallToolRawAsync → PollTaskToCompletionAsync issues tasks/get as fresh POSTs, so IMcpTaskStore MUST be a singleton DI service (or backed by external storage) for the lookup to resolve across polls. Worth a sentence in docs/concepts/tasks/tasks.md and a class-level remarks paragraph on IMcpTaskStore itself.

Nit on the PR body: the "Known limitations" list still includes roots/list as input request — server emits, client doesn't dispatch yet, which is now stale given the dispatch you added.

Things I'd be happy to move to follow-up issues instead of holding this PR for:

• Replacement sample for the removed samples/LongRunningTasks/ (the new doc page covers the concepts, but a runnable sample is more useful for ecosystem adoption).
• A test that pins down what happens when a client sends the tasks _meta opt-in but the server has no TaskStore configured (currently silent fallback to sync — fine if intentional).
• Behavioral coverage for SendTaskStatusNotificationAsync (today there's only round-trip serialization coverage — nothing verifies an actual server→client emission end-to-end, and nothing in the task wrapper auto-emits).
• Make PollTaskToCompletionAsync's stuck-detector threshold (currently MaxConsecutiveStuckPolls = 60) configurable on McpClientOptions — useful for slow networks and debugging.
• Once SEP-2575 server-push (subscriptions/listen / notifications/tasks) lands, wire auto-emit from the task wrapper so the client can opt out of polling.

Thanks!

[halter73]

The CI is red, but my agent claims to know what's up:

root cause is test-only: tests use anonymous types with JsonSerializer.SerializeToElement(...) (no JsonTypeInfo), which falls back to reflection. The test project has JsonSerializerIsReflectionEnabledByDefault=false on net9.0 specifically, so all those tests fail there but pass on net8.0/net10.0/net472. Examples: McpServerTaskTests.cs:184 (_taskStore.FailTask(taskId, new { code = -32000, message = ... }) → flows into JsonSerializer.SerializeToElement(entry.Error) at line 521) and TaskSerializationTests.cs:141 (same shape). Easiest fix is to swap the anonymous types for JsonNode.Parse("""{...}""") or a small named record registered with [JsonSerializable].

[halter73]

LGTM. Thanks!

[jeffhandley]

Submitting as post-merge feedback to consider.

[jeffhandley]

I'm tempted to recommend the spelled-out DefaultTimeToLiveMs because DefaultTtlMs is tough to read, but I don't think my signal is strong enough to actually recommend it. Just a "worth considering for readability" suggestion instead.

[jeffhandley]

Oooh, interesting. If this is only for development/testing scenarios, should we conjure up a new package for dev/test scenarios to keep this kind of API out of the core/production packages?

[halter73]

I don't think it'd be worth it for this one type, and I cannot think of too many other types that would fit. Perhaps the System.IO.Stream-backed transports, StreamServerTransport and StreamClientTransport, but those aren't big either.

I see this as a little more like SignalR having an in-memory backplane by default except it require the developer using it to be even more explicit about relying on an in-memory store. I think that there are plenty of scenarios beyond dev and testing where you have a constrained number of concurrent tasks and it's fine to drop tasks when the process crashes. I see calling out development and testing scenarios as one of the main use cases though.