MCP Tasks: Managing Long-Running Operations

Tasks — Long-Running Operations

By DevShelfHub

Tasks (SEP-1686, introduced 2025-11-25) wrap any MCP request in a durable state machine. The requester polls for results instead of blocking — perfect for expensive computations and batch jobs.

Series progress12 / 23

When to use tasks

Use tasks for

Tool calls that take more than a few seconds
Batch processing (1000 docs to summarise)
External jobs (running a Spark query, training a model)
Multi-step workflows with intermediate input

Don't use tasks for

Sub-second operations
Streaming responses that fit in a single call
Real-time progress (use progressToken instead)

The TaskStatus state machine

created
   ↓
working ⇄ input_required
   ↓
[completed | failed | cancelled]   ← terminal

working — actively running.
input_required — paused; requester must provide more data via tasks/inputResponse.
completed / failed / cancelled — terminal; cannot leave.

Polling for status

tasks/get response

{
  "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
  "status": "working",
  "statusMessage": "Indexing 4,201 files...",
  "createdAt": "2025-11-25T10:30:00Z",
  "lastUpdatedAt": "2025-11-25T10:30:12Z",
  "ttl": 30000,
  "pollInterval": 5000
}

Respect pollInterval — receivers may rate-limit aggressive pollers.

Retrieving results & cancelling

Once status is completed, call tasks/result to fetch the payload. To abort early, call tasks/cancel:

{ "method": "tasks/cancel", "params": { "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840" } }

Task errors

Code	When
-32602	Unknown taskId / cursor; cancellation of a terminal task.
-32603	Internal error.
-32600	Non-task request when the receiver requires task augmentation.

Quick summary

Tasks are durable state machines for long operations
Status: working ↔ input_required → completed | failed | cancelled (terminal)
Poll tasks/get on the recommended pollInterval; fetch results via tasks/result
Receivers MUST enforce auth-context filtering on tasks/list

MCP Tasks FAQ

What is the MCP Tasks primitive?

The MCP Tasks primitive (SEP-1686) wraps any MCP request in a durable state machine. Instead of waiting for the result, the requester receives a task ID and polls for status — ideal for computations that take minutes, not milliseconds.

What are the lifecycle states of an MCP Task?

An MCP Task progresses through these states: submitted (received but not started), working (actively executing), completed (result available), failed (terminal error), and cancelled (cancelled by request).

How do you poll for MCP Task results?

Use the tasks/get method with the task ID returned at submission. Poll until the status transitions to completed, failed, or cancelled. Servers can also push updates via notifications/tasks/updated if the client subscribes.

Can MCP Tasks be cancelled?

Yes. Send a tasks/cancel request with the task ID. The server transitions the task to cancelled state. Tasks that have already completed or failed cannot be cancelled.

Is the MCP Tasks API stable?

As of 2025-11-25, MCP Tasks (SEP-1686) is experimental. The API may change in future spec revisions. Check the current MCP spec and your SDK's changelog before using Tasks in production.