Support the MCP Tasks extension (SEP-2663) in McpToolset: expose the mcp 2.x client extension seam

[zeishr]

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

🔴 Required Information

Is your feature request related to a specific problem?

We run an MCP server that fronts physical hardware. A reboot, a firmware flash or an instrumented run takes minutes, not seconds — and the call is behind an HTTP gateway with its own write timeout, so "just hold the connection open" is not available to us.

Today McpToolset has exactly one shape for a tool call: session.call_tool(...) awaited to a CallToolResult (mcp_tool.py:470-475, verified at main@1cd6f464). The only relief valves are sse_read_timeout (default 300s, mcp_session_manager.py:218) and progress notifications (#3398), and neither gives a durable handle — a dropped connection loses the operation outright.

So servers like ours split one operation into start_x / x_status / x_result tools and let the model drive the polling loop. That is unreliable (it depends on prompt engineering), it burns context, and it is the exact anti-pattern the MCP spec set out to remove.

MCP has a standard answer now: the Tasks extension, identifier io.modelcontextprotocol/tasks, specified in SEP-2663 (merged 2026-05-15) and maintained at modelcontextprotocol/ext-tasks. The server decides per request that the work is long-running and answers tools/call with resultType: "task" plus a taskId; the client polls tasks/get at the server's pollIntervalMs until a terminal status and reads the final result. One tool declaration, no extra tools in the model's context, and the handle survives a reconnect.

McpToolset has no path to this. There is no protocol-level task anywhere under src/google/adk/tools/mcp_tool/, and #3449 has no entry for it.

To be clear about what this is not: this is not the experimental 2025-11-25 tasks (SEP-1686). SEP-2663 removed those from the core spec, and in the mcp 1.x SDK both ClientSession.experimental and mcp.client.experimental.task_handlers are deprecated for removal in 2.0 (mcp/client/session.py:25-28 in mcp==1.29.0). Nothing here asks for that design — in particular not the Tool.execution.taskSupport / tools/list warmup handshake, which SEP-2663 deliberately dropped in favour of a single capability-level opt-in.

Describe the Solution You'd Like

Two steps. The first is small and is the one we actually need.

1. Pass the mcp 2.x client extension seam through McpToolset.

mcp==2.0.0 gives ClientSession.__init__ three new keyword arguments — extensions, result_claims, notification_bindings (mcp/client/session.py:385-387) — which are precisely the machinery an extension needs: extensions advertises the identifier in per-request client capabilities, and a ResultClaim keyed on resultType folds a non-core result shape into tools/call parsing.

ADK already threads sampling_callback / sampling_capabilities / elicitation_callback down exactly the chain those arguments would follow:

• McpToolset.__init__ — mcp_toolset.py:171-173
• → MCPSessionManager — mcp_toolset.py:256-262, mcp_session_manager.py:543-545
• → SessionContext — mcp_session_manager.py:1011-1019
• → ClientSession — session_context.py:347-369

Adding the three extension kwargs to that same chain is the same shape of change as the elicitation plumbing in #6422, and it lets Tasks — or any other official extension — be implemented outside ADK without forking the toolset.

This depends on the mcp 2.x bump tracked in #6532 / #6537 and only makes sense on top of it.

2. Ship Tasks natively in the toolset (follow-up).

Opt-in, off by default. When it is on and the server advertises io.modelcontextprotocol/tasks, McpToolset advertises it too; on a resultType: "task" response it polls tasks/get at the server's pollIntervalMs until terminal, returns the result as the tool's CallToolResult, and sends tasks/cancel if the invocation is cancelled. The agent sees the same tool and the same result it sees today — only the wire changes.

For callers that want the handle rather than a blocking poll, BaseTool.is_long_running (base_tool.py:59) is the natural mapping, but that can wait; blocking-with-polling already solves the timeout and reconnect problems.

Impact on your work

This is blocking for us. Every hardware operation either has to fit inside an HTTP write timeout or be re-expressed as a start/status/result triplet with the model as the scheduler. Step 1 alone unblocks us, because we can then carry the extension ourselves.

No timeline pressure beyond #6532 — we are not asking for anything before the mcp 2.x bump lands.

Willingness to contribute

Yes. Happy to send the step-1 pass-through PR on top of #6537, and to prototype step 2 against a Tasks conformance server.

---

🟡 Recommended Information

Describe Alternatives You've Considered

• start / status / result tool triplets. What we do today. Model-driven polling, so it depends on prompt engineering to happen at all, and it costs a model turn per poll. This is the motivating problem in SEP-1686 and SEP-2663.
• Raising sse_read_timeout and blocking longer. Intermediaries cap the request duration regardless, and a blocked call has no crash resilience: if the connection drops, the result is gone with no handle to resume from.
• Progress notifications (Support for MCP Progress, Notifications, and Logging in MCP Toolset #3398). They give visibility into a call that is still open. They do not give a durable handle, and the call still has to stay open.
• Subclassing McpTool to poll ourselves. Two blockers: extension negotiation happens on the ClientSession, which the toolset owns and does not expose; and the toolset constructs the McpTool instances itself (mcp_toolset.py:518-527), so there is no supported injection point.

Proposed API / Implementation

Step 1, as a pass-through:

# google/adk/tools/mcp_tool/mcp_toolset.py
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=...),
    # forwarded verbatim to mcp.ClientSession, like sampling_callback today
    extensions={"io.modelcontextprotocol/tasks": {}},
    result_claims={"io.modelcontextprotocol/tasks": [tasks_claim]},
)

Step 2, as an opt-in on the same object:

toolset = McpToolset(
    connection_params=...,
    # advertise the extension, and resolve `resultType: "task"` by polling
    # tasks/get until terminal before returning the CallToolResult
    enable_tasks=True,
)

Additional Context

• Extension identifier and negotiation: https://modelcontextprotocol.io/extensions/tasks/overview
• SEP-2663 (merged 2026-05-15): SEP-2663: Tasks Extension modelcontextprotocol/modelcontextprotocol#2663
• Extension spec repository: https://github.com/modelcontextprotocol/ext-tasks (self-described as experimental; the negotiation mechanism it relies on is stable in 2026-07-28)
• The Tasks extension is not yet listed in the extension client matrix, so as far as we can tell no major host ships it yet. Step 1 is what lets ADK users move without waiting on that.

[sanketpatil06]

Hi @zeishr, thanks for bringing this. If you have a solution in mind please feel free to raise a PR, our team will be happy to review it. We appreciate your contribution.

[zeishr]

Hi @zeishr, thanks for bringing this. If you have a solution in mind please feel free to raise a PR, our team will be happy to review it. We appreciate your contribution.

Ok thanks, on it !

[zeishr]

Thanks @sanketpatil06 — starting on it.

Plan, after verifying the details against the released mcp==2.0.0 / mcp-types==2.0.0 wheels rather than the SDK's main:

Two PRs, not three. The mcp 2.x bump (#6532) first, then step 1 and step 2 from the description together in a second PR as two separate commits. I originally proposed the seam as its own change, but a seam with no in-tree consumer is hard to review on its merit, and Tasks is the consumer that justifies it. Splitting them back out is a one-command operation if you'd rather review them apart. I've asked on #6532 whether the 2.x packages are importable internally yet, since that decides whether the bump PR should come from me at all.

Corrections to my own description, from the verification pass:

• ClientSession does not resolve a claim for you. call_tool raises UnexpectedClaimedResult on a claimed result unless called with allow_claimed=True, and it never calls claim.resolve — the high-level mcp.Client does that (by_model[type(result)] → resolve → validate_tool_result). ADK uses the low-level ClientSession, so passing the three kwargs through is necessary but not sufficient: the toolset also needs that resolution step, otherwise the seam can't actually carry an extension. Step 1 grew slightly.
• Claims are inert unless the connection negotiated 2026-07-28. _claim_active requires version in MODERN_PROTOCOL_VERSIONS, and _build_capabilities drops claim-bearing identifiers from the ad at legacy versions. ClientSession.initialize() always performs the pre-2026 handshake (LATEST_HANDSHAKE_VERSION == "2025-11-25"), and that is what SessionContext calls today — so with initialize() alone, Tasks could never activate, no matter what is passed to the constructor. The toolset needs discover() with an initialize() fallback, like Client(mode="auto"). I'll gate discover-first on "extensions were actually configured" so the default path stays byte-identical and nobody pays a new probe or a new failure mode for a feature they didn't ask for.
• There is no Python implementation of SEP-2663 anywhere yet: modelcontextprotocol/ext-tasks ships TypeScript types and a JSON Schema only, python-sdk#3005 (server side) is unmerged, and python-sdk#3226 (client side) is open. The task types that are in mcp-types 2.0.0 are the old 2025-11-25 in-core design and are wire-incompatible (nested task, ttl instead of ttlMs, notifications/tasks/status), so ADK has to carry its own wire models for now. I'll keep every one of them private in a _tasks.py, so that when upstream ships #3226 the internals can be swapped for it with no change to ADK's public API.

Good news from the same pass: no monkeypatching or raw JSON-RPC is needed. send_request takes an arbitrary Request plus a result model, and it stamps the Mcp-Name header generically from the request's name_param class attribute — which mcp-types documents as being there precisely because SEP-2663 requires it for tasks/*. A flat CreateTaskResult model with snake_case fields round-trips the spec's example wire payload exactly, and ResultClaim accepts it.

Scope for v1, unchanged from the description: blocking-with-polling, opt-in, off by default. tasks/get at the server's pollIntervalMs until terminal, the final result returned as the tool's CallToolResult, best-effort tasks/cancel on cancellation. A task that goes to input_required will be cancelled and reported as an error result — bridging tasks/update to the existing elicitation_callback is a natural follow-up, but upstream hasn't settled that question either (it's an open one on #3226), so I'd rather not invent it here. notifications/tasks and the deferred-handle mapping onto is_long_running also stay out.

I'll include a sample with a working SEP-2663 server so there's something to run it against — MCPServer in 2.0 supports custom extensions with method bindings, so it can be a real server rather than a mock.