Module tasks 

Tasks API for durable long-running operations

The Tasks API (MCP 2025-11-25, SEP-1686) provides durable state machines for long-running operations, enabling requestor polling and deferred result retrieval.

Overview

Tasks enable:

• Durable state machines - Long-running operations that outlive individual connections
• Requestor polling - Clients can poll for completion status
• Deferred results - Results available after task completion
• Input requests - Tasks can request additional input during execution
• Bidirectional support - Works for both client→server and server→client requests

Key Concepts

Task Lifecycle

[*] → working
    ↓
    ├─→ input_required ──┬─→ working ──→ terminal
    │                    └─→ terminal
    │
    └─→ terminal

Terminal states: completed, failed, cancelled

Supported Requests

Client → Server (Server as receiver):

• tools/call - Long-running tool execution

Server → Client (Client as receiver):

• sampling/createMessage - LLM inference operations
• elicitation/create - User input collection

Usage Example

use turbomcp_protocol::types::tasks::{Task, TaskStatus, TaskMetadata, CreateTaskResult};
use turbomcp_protocol::types::CallToolRequest;
use serde_json::json;

// Client requests task-augmented tool call
let request = CallToolRequest {
    name: "long_running_analysis".to_string(),
    arguments: Some(json!({"data": "large_dataset"})),
    task: Some(TaskMetadata {
        ttl: Some(300_000), // 5 minute lifetime
    }),
    _meta: None,
};

// Server responds immediately with task
let response = CreateTaskResult {
    task: Task {
        task_id: "task-123".to_string(),
        status: TaskStatus::Working,
        status_message: None,
        created_at: "2025-11-25T10:30:00Z".to_string(),
        ttl: Some(300_000),
        poll_interval: Some(5_000), // Poll every 5s
    },
    _meta: None,
};

// Client polls for status
// ... tasks/get request ...

// When completed, retrieve results
// ... tasks/result request ...

Security Considerations

Task ID Access Control

Task IDs are the primary access control mechanism. Implementations MUST:

1. Bind to authorization context - Reject operations from different contexts
2. Use cryptographic entropy - Task IDs must be unpredictable (use UUID v4)
3. Enforce TTL limits - Shorter TTLs reduce exposure windows
4. Audit access - Log all task operations for security monitoring

Resource Management

Implementations SHOULD:

• Enforce concurrent task limits per requestor
• Enforce maximum TTL durations
• Clean up expired tasks promptly
• Implement rate limiting on task operations

Structs

CancelTaskRequest

Request to cancel a task

CreateTaskResult

Result type for task creation (immediate response to task-augmented requests)

GetTaskPayloadRequest

Request to retrieve task results (or receive input requests during input_required)

GetTaskPayloadResult

Response from tasks/result containing the actual operation result

GetTaskRequest

Request to retrieve task status

ListTasksRequest

Request to list all tasks (with pagination)

ListTasksResult

Response from tasks/list containing paginated task list

RelatedTaskMetadata

Metadata for associating messages with a task

Task

Core task type representing a long-running operation

TaskMetadata

Metadata for requesting task augmentation on a request

TaskStatusNotification

Task status change notification (optional, not required by spec)

Enums

TaskStatus

Task status representing the current state of a long-running operation

Type Aliases

CancelTaskResult

Response from tasks/cancel containing updated task with cancelled status

GetTaskResult

Response from tasks/get containing current task status