What is MCP Tasks?
MCP Tasks is the official `io.modelcontextprotocol/tasks` Extension that lets an MCP Server return a durable task handle for a long-running Tool call instead of keeping the original request blocked.
Quick Facts
| Full Name | Model Context Protocol Tasks Extension |
|---|---|
| Created | 2026 as an official MCP Extension |
| Specification | Official Specification |
How It Works
When a Task is appropriate
Use a Task when work can outlive normal request timeouts, must survive reconnects, maps to an external job ID, or pauses for human input. CI pipelines, deployments, batch processing, and model training are typical examples. Do not use a Task merely to avoid optimizing a slow synchronous Tool. Progress notifications alone do not provide deferred result retrieval, while a Task handle does not automatically make execution durable.
Capability and result contract
The Client includes io.modelcontextprotocol/tasks in the Extension map of its per-request Capabilities, and the Server advertises the same identifier through server/discover. The current Extension augments tools/call. A supporting Client must accept either the ordinary complete result or a CreateTaskResult with resultType: "task"; the Server decides per call and must never return a Task to a Request that did not declare support.
Lifecycle and mid-flight input
Task states are working, input_required, completed, failed, and cancelled; the final three are terminal. Clients call tasks/get and respect the current pollIntervalMs. When a Task becomes input_required, its inputRequests can carry Elicitation or other supported requests, and the Client sends matching inputResponses through tasks/update. A completed Task contains the original Tool result, including a valid Tool result whose isError is true.
Durability, identity, and effects
The Server must make a Task retrievable before returning its handle and retain it for the advertised TTL. Durable storage should bind the Task to the authenticated Principal, Tenant, originating Tool and argument digest, Server build, policy revision, and backend job. Task IDs should be unguessable but are not authorization by themselves. Side effects still need idempotency keys, effect records, reconciliation, and explicit unknown-outcome handling after crashes.
Cancellation, notifications, and operations
tasks/cancel records cancellation intent, but cancellation is cooperative and the Task may still finish in another terminal state. Polling is the baseline; subscribed Clients can receive full Task states through notifications/tasks, then confirm as needed. Bound polling, concurrent Tasks, retained state, result size, input wait time, retries, and worker leases. Trace state transitions and final effects without logging secrets or unrestricted payloads.
Key Characteristics
- Official optional Extension: identified by `io.modelcontextprotocol/tasks` and negotiated by both peers
- Server-directed polymorphism: one Tool call can return an ordinary result or a durable Task handle
- Poll-based recovery: `tasks/get` retrieves state and final output after reconnects
- Mid-flight interaction: `input_required` Tasks receive matching responses through `tasks/update`
- Cooperative cancellation: acknowledgement records intent but does not prove work stopped or rolled back
- Effect-aware durability: Task state, authorization, idempotency, retention, and backend outcome remain Server duties
Common Use Cases
- Tracking a CI pipeline or deployment that can run beyond an HTTP timeout
- Wrapping an existing cloud job API whose durable job ID maps to a Task
- Pausing a long-running operation for a user approval or missing field
- Recovering batch processing status after a Client or network restart
- Returning a final artifact or structured Tool result after asynchronous processing
Example
Loading code...Frequently Asked Questions
How is an MCP Task different from progress notifications?
Progress notifications describe work while the originating Request is active. A Task is a durable state machine with a retrievable handle, polling, retained terminal output, mid-flight input, and reconnect recovery. A Server can support either or both, but progress alone cannot recover a result after the response path is lost.
Can every MCP operation return a Task?
No. The current Tasks Extension supports task-augmented `tools/call`. The Client must declare the Extension on that Request, and the Server may still return an ordinary result. Implementations should allow future request types internally without claiming unsupported methods today.
Does tasks/cancel guarantee that the operation stopped?
No. Cancellation is cooperative. The Server acknowledges the request and should propagate it, but the worker or downstream system may already have committed work or may not support cancellation. The Client must poll for the actual terminal state, and consequential effects require separate reconciliation.
How should MCP Task IDs be secured?
Generate high-entropy identifiers and bind every read, update, and cancel operation to the authenticated Principal, Tenant, Tool, and authorization context. Do not treat possession of an ID as sufficient permission. Apply retention limits, avoid enumeration, redact IDs when sensitive, and prevent one caller from probing another caller's state.
When should a Tool stay synchronous instead of creating a Task?
Keep it synchronous when work reliably completes within the request budget and reconnect recovery or mid-flight input adds no value. Tasks add storage, polling, authorization, retention, worker coordination, and failure-recovery costs, so adopt them for a measured lifecycle need rather than every slow call.