Implement Tasks capability for MCP spec 2025-11-25

[ezynda3]

Summary

Implement the Tasks capability for MCP specification version 2025-11-25. This feature is mentioned in the spec but requires further investigation to understand the complete requirements.

Specification Reference

• Spec URL: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
• Mentioned in:
  • Lifecycle capability negotiation for both client and server
  • Server capabilities: tasks with sub-capabilities like list, cancel, and nested requests

Current Implementation

Status: Not implemented

No references to "tasks" or "Tasks" capability found in the codebase except in example comments.

Spec References from Lifecycle Section

From the initialization example in the spec:

Client Capabilities

{
  "capabilities": {
    "tasks": {
      "requests": {
        "elicitation": {
          "create": {}
        },
        "sampling": {
          "createMessage": {}
        }
      }
    }
  }
}

Server Capabilities

{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "tools": {
          "call": {}
        }
      }
    }
  }
}

Interpretation from Spec

Based on the capability structure, the Tasks feature appears to enable:

1. Task Management:

   • list: Enumerate active tasks
   • cancel: Cancel a running task

2. Task-Augmented Requests:

   • Servers can make requests (like tool calls) that return immediately with a task ID
   • Clients can make requests (like elicitation, sampling) that return immediately with a task ID
   • Progress can be tracked via task ID
   • Results delivered asynchronously when task completes

This would enable long-running operations to be non-blocking.

Investigation Needed

Before implementation, we need to:

• Review the full Tasks specification at https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
• Understand the relationship between tasks and existing Progress/Cancellation features
• Determine the task lifecycle (created, running, completed, failed, cancelled)
• Define the task identifier format
• Understand how tasks relate to request IDs
• Clarify notification flow for task state changes

Potential Type Definitions

Based on the capability structure, here's a preliminary sketch:

// Task lifecycle states
const (
    TaskStatePending   = "pending"
    TaskStateRunning   = "running"
    TaskStateCompleted = "completed"
    TaskStateFailed    = "failed"
    TaskStateCancelled = "cancelled"
)

// Task represents an asynchronous operation
type Task struct {
    ID       string         `json:"id"`
    State    string         `json:"state"`
    Progress *ProgressInfo  `json:"progress,omitempty"`
    Result   any            `json:"result,omitempty"`
    Error    *JSONRPCError  `json:"error,omitempty"`
}

// List tasks request
type ListTasksRequest struct {
    Method string              `json:"method"`
    Params ListTasksParams     `json:"params"`
}

type ListTasksParams struct {
    Meta *Meta `json:"_meta,omitempty"`
}

type ListTasksResult struct {
    Tasks []Task `json:"tasks"`
}

// Cancel task request
type CancelTaskRequest struct {
    Method string           `json:"method"`
    Params CancelTaskParams `json:"params"`
}

type CancelTaskParams struct {
    Meta   *Meta  `json:"_meta,omitempty"`
    TaskID string `json:"taskId"`
}

// Task state change notification
type TaskStateChangedNotification struct {
    Method string                          `json:"method"`
    Params TaskStateChangedNotificationParams `json:"params"`
}

type TaskStateChangedNotificationParams struct {
    TaskID string `json:"taskId"`
    State  string `json:"state"`
}

Capability Definition

// Client capabilities
type TasksClientCapability struct {
    Requests *TasksRequestsCapability `json:"requests,omitempty"`
}

type TasksRequestsCapability struct {
    Elicitation *ElicitationTasksCapability `json:"elicitation,omitempty"`
    Sampling    *SamplingTasksCapability    `json:"sampling,omitempty"`
}

type ElicitationTasksCapability struct {
    Create *struct{} `json:"create,omitempty"`
}

type SamplingTasksCapability struct {
    CreateMessage *struct{} `json:"createMessage,omitempty"`
}

// Server capabilities
type TasksServerCapability struct {
    List     *struct{}                `json:"list,omitempty"`
    Cancel   *struct{}                `json:"cancel,omitempty"`
    Requests *TasksRequestsCapability `json:"requests,omitempty"`
}

type ToolTasksCapability struct {
    Call *struct{} `json:"call,omitempty"`
}

Files to Create/Modify

Once the spec is fully understood:

• New file: mcp/tasks.go - Task types and constants
• Update: mcp/types.go - Add Tasks capabilities to ClientCapabilities and ServerCapabilities
• New file: server/tasks.go - Server-side task management
• Update: server/server.go - Add task handlers (list, cancel)
• New file: client/tasks.go - Client-side task tracking
• Update: client/client.go - Handle task-related notifications

Implementation Considerations

1. Task Storage: How/where to store task state (in-memory, persistent?)
2. Task IDs: Format and uniqueness guarantees
3. Cleanup: When to remove completed tasks
4. Concurrency: Thread-safety for task state updates
5. Relationship to existing features:
   • How tasks interact with Progress notifications
   • How tasks interact with Cancellation
   • Whether tasks replace or complement these features

Testing Requirements

• Unit tests for task lifecycle state machine
• Test task list pagination (if supported)
• Test task cancellation
• Test task-augmented tool calls
• Test task-augmented sampling/elicitation
• Integration tests for async operation flows

Implementation Priority

Priority: Low - This feature requires more spec investigation and may not be critical for basic MCP 2025-11-25 compliance. Mark as "help wanted" for community contribution.

Next Steps

1. Thoroughly review the Tasks specification section
2. Create a design document outlining the implementation approach
3. Get feedback from maintainers on design
4. Implement based on approved design

Current implementation status: Not implemented (as of commit 670a95a)

[alsenz]

@ezynda3 this is a really important feature for our product roadmap in Q1 26.

I note @JAORMX's initial contribution in #635. I would be pleased to contribute the remaining topics (tool augmented flow, client side, examples and documentation) to help us get started.

I would have a couple of clarifications and/or questions.

1. Clarification - I presume the intended design is for users to manage creating their own task IDs? I think this would be beneficial because we are often proxying another API with its own workflow identifiers so it would be natural to re-use these, and if they don't have this the SDK could create one.

2. Question - The part of the specification with the hardest implementation impact is probably Tasks §3.4 (Tool Level Negotiation) wherein tools may sometimes be augmented with optional task results- i.e. the same tool may be able to either immediately return a CreateTaskResult or eventually return a CallToolResult. This forces the SDK implementation to design interfaces which support that a tool handler may return either response. I think there are three possible approaches:

• (a) The existing tool handler func signature is changed to support one of either CreateTaskResult or CallToolResult being returned. My proposed solution would be to change the ToolHandlerFunc signature to
  type ToolHandlerFunc func(ctx context.Context, request mcp.CallToolRequest) (mcp.AnyToolResult, error)
  where AnyToolResult is an interface implemented by both *CreateTaskResult and *CallToolResult, to minimise user migration effort.
• (b) MCPServer AddTool method is supplemented by functional options that drive task data flow, but this risks redundancy for task-only tools and introduces validation burden.
• (c) MCPServer gets AddTaskAugmentedTool with a new tool handler function signature.

Personally, I think I most like (a) because whilst this is technically a breaking change, it would be one type change to users' handler function definitions and no change to the body of their code. However, it is still breaking so would be interested in the maintainers' views.