.NET: [BREAKING] Migrate MCP long-running task support to the 2026-07-28 Tasks extension

[Peter Ibekwe (peibekwe)]

Motivation & Context

Microsoft.Agents.AI.Mcp implemented long-running MCP tool calls against the experimental Tasks protocol introduced in MCP specification 2025-11-25, and the repository pinned ModelContextProtocol 1.2.0.

MCP 2026-07-28 moved Tasks into the official io.modelcontextprotocol/tasks extension: capability negotiation became per-request extension opt-in rather than per-tool execution.taskSupport. The old and new designs share neither API nor wire compatibility, so the previous implementation could not interoperate with current MCP peers and blocked the move to the C# SDK 2.x line.

This change lets an agent invoke long-running MCP tools against 2026-07-28 servers while the tool loop stays unaware that a task was involved.

Description & Review Guide

• What is the impact of these changes?
  • Microsoft.Agents.AI.Mcp is alpha, and its task-related surface changes without shims: ListAgentToolsWithTaskSupportAsync is replaced by ListAgentToolsWithTasksAsync. McpTaskOptions remains but is redesigned: the obsolete TTL option is removed, remote cancellation remains configurable, and limits are added for stuck polling and total unique input requests.
  • The wrapper retains the created task handle and sends best-effort tasks/cancel by default when local cancellation occurs or when a non-terminal lifecycle failure makes further polling impossible. Cancellation cleanup uses an independent five-second timeout and never masks the original exception.
  • Server-provided polling intervals are validated before use, and unique mid-flight input requests are bounded to protect client resources. These limits are configurable through McpTaskOptions.
  • Repository-wide dependency impact: MCP 2.1.0 forces three central version bumps to resolve NU1109 - Microsoft.Bcl.Memory 10.0.5 → 10.0.10, System.Collections.Immutable 10.0.1 → 10.0.10, and System.Net.ServerSentEvents` 10.0.8 → 10.0.10.
  • Tasks require both peers to negotiate 2026-07-28; down-level peers transparently receive ordinary synchronous tool results.

Fixes #7773

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Migrates .NET MCP task support to the MCP 2026-07-28 Tasks extension and SDK 2.1.0.

Changes:

• Replaces the legacy task API with transparent extension negotiation and polling.
• Updates tests, samples, authentication APIs, and documentation.
• Upgrades MCP and required transitive dependency versions.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
DefaultMcpToolHandlerTests.cs	Suppresses expected legacy-content diagnostics.
TestTools.cs	Removes legacy task-support metadata.
TaskAwareMcpClientAIFunctionTests.cs	Tests task polling, fallback, input, results, and cancellation.
Microsoft.Agents.AI.Mcp.UnitTests.csproj	Adds the Tasks extension package.
McpTaskOptionsTests.cs	Removes obsolete option tests.
ListAgentToolsWithTaskSupportTests.cs	Removes legacy API tests.
ListAgentToolsWithTasksTests.cs	Tests the replacement listing API.
InMemoryMcpServerFixture.cs	Adds extension-enabled task test infrastructure.
EmptyServiceProvider.cs	Removes obsolete fixture helper.
TaskAwareMcpClientAIFunction.cs	Delegates task lifecycle handling to SDK 2.1.
Microsoft.Agents.AI.Mcp.csproj	Adds Tasks extension dependency and metadata.
McpTaskOptions.cs	Removes the legacy task options API.
McpClientTaskExtensions.cs	Introduces ListAgentToolsWithTasksAsync.
FoundryToolboxService.cs	Updates negotiation documentation.
HostedWorkflowHandoff.csproj	Upgrades MCP to 2.1.0.
HostedToolboxMcpSkills.csproj	Upgrades MCP to 2.1.0.
HostedMcpTools.csproj	Upgrades MCP to 2.1.0.
ModelContextProtocol/README.md	Updates the task sample description.
Agent_MCP_Server_Auth/Program.cs	Migrates the OAuth callback API.
Agent_MCP_LongRunningTask_Client/README.md	Documents the new Tasks lifecycle.
Agent_MCP_LongRunningTask_Client/Program.cs	Migrates the client and server sample.
Agent_MCP_LongRunningTask_Client.csproj	Adds the Tasks extension dependency.
AgentsSamples.cs	Updates sample output verification.
Directory.Packages.props	Upgrades MCP and supporting dependencies.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 9c5c6948bbbd
Model: gpt-5.6-sol

Overview

The PR cleanly migrates task invocation to the 2026-07-28 extension, delegates negotiation and polling to the MCP SDK, and adds in-process coverage for task-backed, inline-fallback, elicitation, result-projection, and cancellation paths. The SDK validates OAuth callback state and issuer values supplied by the updated sample, and the alpha package explicitly documents its API break. The remaining lifecycle regression is that cancelling an agent invocation no longer cancels remote work, so abandoned long-running tasks can continue consuming server resources.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI.Mcp/TaskAwareMcpClientAIFunction.cs

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (2)

dotnet/src/Microsoft.Agents.AI.Mcp/McpTaskOptions.cs:20

• The PR description says McpTaskOptions is removed, but this change keeps it public and adds MaxConsecutiveStuckPolls. That materially misstates the breaking API surface for release-note consumers; update the description to say only the old listing method/TTL option were removed and document the retained options type.

    public bool CancelRemoteTaskOnLocalCancellation { get; set; } = true;

dotnet/src/Microsoft.Agents.AI.Mcp/TaskAwareMcpClientAIFunction.cs:99

• This now explicitly sends tasks/cancel after local cancellation, while the PR description says cancellation only stops local polling and server work continues because no task ID is available. The sample README also documents this new default, so update the PR description to reflect the implemented remote-cancellation behavior and its opt-out.

            catch (OperationCanceledException) when (
                this._cancelRemoteTaskOnLocalCancellation &&
                cancellationToken.IsCancellationRequested)
            {
                await this.TryCancelTaskAsync(taskId).ConfigureAwait(false);

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 1 net-new commit(s): 610e124fb5c6
Model: gpt-5.6-sol

Overview

The incremental change replaces SDK-managed polling with an explicit task lifecycle so the wrapper can retain the task ID and remotely cancel work after local cancellation. It adds strong coverage for successful polling, terminal states, input resolution, stuck input, cancellation, and intentional detachment. Residual risks remain because fresh server-provided input keys can bypass the stuck-task bound, server-controlled poll intervals are not validated, and non-cancellation polling failures abandon remote tasks.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (1 high, 2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI.Mcp/TaskAwareMcpClientAIFunction.cs