Add the SEP-2663 Tasks extension (core)

KL
3mo ago
+3275-74

Summary

The SEP-2663 Tasks extension (io.modelcontextprotocol/tasks) — the conformant core. Built on the extension API from #3003 (this PR is based on that branch; merge after it).

SEP-2663 (Final) is wire-incompatible with the 2025-11-25 in-core Tasks design still carried (types-only) in mcp_types, so the extension defines its own SEP-2663-shaped models.

from mcp.server.mcpserver import MCPServer
from mcp.server.tasks import Tasks

mcp = MCPServer("demo", extensions=[Tasks()])

What's implemented (conformant core)

  • Server-decided augmentation. The server chooses, per request, to defer a tools/call as a task. The legacy params.task field is ignored (it is not the opt-in). Only a client that declared the extension on a modern (2026-07-28) connection is augmented — a legacy handshake cannot carry the capability back, so it is never augmented.
  • Envelope. A task-augmented tools/call returns a flat CreateTaskResult (resultType: "task", taskId/status/createdAt/lastUpdatedAt/ttlMs).
  • tasks/get returns a DetailedTask (resultType: "complete"); a completed task inlines the original CallToolResult. A tool result with isError: true is a completed task (failed is reserved for JSON-RPC errors).
  • tasks/cancel is an empty ack. tasks/result is not registered → -32601 (removed in SEP-2663). A tasks/* call from a non-declaring client → -32003 with a requiredCapabilities payload. Task ids are entropy-bearing bearer capabilities.

Ships a runnable tasks story and a migration note.

Deferred to follow-ups

Each needs deeper SDK plumbing and is called out in the module/README/migration:

  • tasks/update + the MRTR input_required loop
  • ToolExecution.taskSupport gating with the -32021 required-task error
  • notifications/tasks
  • SEP-2243 task routing headers

These map to the remaining conformance tasks-* scenarios; the core targets tasks-dispatch-and-envelope, tasks-capability-negotiation, tasks-wire-fields, tasks-lifecycle (partial), tasks-request-state-removal.

Testing

14 spec-derived in-memory Client(server) tests, 100% coverage of tasks.py, strict-no-cover clean, pyright + ruff + markdownlint green, both story legs (in-memory + http-asgi) pass.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.