SEP-1686: Tasks

​

Abstract

​

Motivation

1. start_long_running_tool: This would start the work represented by long_running_tool and return a tracking token of some kind, such as a job ID.
2. get_long_running_tool_status(token): This would accept the tracking token and return the current status of the tool call, informing the caller that the operation is still ongoing.
3. get_long_running_tool_result(token): This would accept the tracking token and return the result of the tool call, if it is available.

• Leverage Existing State Management: Systems like AWS Step Functions, Workflows for Google Cloud, and CI/CD platforms already maintain execution state, logs, and results. MCP servers can expose these systems’ existing APIs without pushing the responsibility of polling to a fallible agent.
• Preserve Native Monitoring: Existing monitoring, alerting, and observability tools continue to work unchanged. The execution happens almost entirely within the existing workflow-management system.
• Reduce Implementation Overhead: Server implementers don’t need to build new state management, persistence, or monitoring infrastructure. They can focus on the MCP protocol mapping of their existing APIs to tasks.

​

Specification

​

1. User Interaction Model

​

2. Capabilities

​

3. Protocol Messages

​

3.1. Creating Tasks

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
        "keepAlive": 60000
      }
    }
  }
}

​

3.2. Getting Tasks

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/get",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "keepAlive": 30000,
    "pollFrequency": 5000,
    "status": "submitted",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

​

3.3. Retrieving Task Results

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tasks/result",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false,
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

​

3.4. Task Creation Notification

{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/created",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

​

3.5. Listing Tasks

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tasks/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "tasks": [
      {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
        "status": "working",
        "keepAlive": 30000,
        "pollFrequency": 5000
      },
      {
        "taskId": "abc123-def456-ghi789",
        "status": "completed",
        "keepAlive": 60000
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

​

3.6 Deleting Tasks

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tasks/delete",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

​

4. Behavior Requirements

​

4.1. Task Support and Handling

1. Receivers that do not support task augmentation on a request MUST process the request normally, ignoring any task metadata in _meta.
2. Receivers that support task augmentation MAY choose which request types support tasks.

​

4.2. Task ID Requirements

1. Task IDs MUST be a string value.
2. Task IDs SHOULD be unique across all tasks controlled by the receiver.
3. The receiver of a request with a task ID in its _meta MAY validate that the provided task ID has not already been associated with a task controlled by that receiver.

​

4.3. Task Status Lifecycle

1. Tasks MUST begin in the submitted status when created.
2. Receivers MUST only transition tasks through the following valid paths:
   1. From submitted: may move to working, input_required, completed, failed, cancelled, or unknown
   2. From working: may move to input_required, completed, failed, cancelled, or unknown
   3. From input_required: may move to working, completed, failed, cancelled, or unknown
   4. Tasks in completed, failed, cancelled, or unknown status MUST NOT transition to any other status (terminal states)
3. Receivers MAY move directly from submitted to completed if execution completes immediately.
4. The unknown status is a terminal fallback state for unexpected error conditions. Receivers SHOULD use failed with an error message instead when possible.

​

4.4. Input Required Status

1. When a receiver sends a request associated with a task (e.g., elicitation, sampling), the receiver MUST move the task to the input_required status.
2. The receiver MUST include the modelcontextprotocol.io/related-task metadata in the request to associate it with the task.
3. When the receiver receives all required responses, the task MAY transition out of input_required status (typically back to working).
4. If multiple related requests are pending, the task SHOULD remain in input_required status until all are resolved.

​

4.5. Keep-Alive and Resource Management

1. Receivers MAY override the requested keepAlive duration.
2. Receivers MUST include the actual keepAlive duration (or null for unlimited) in tasks/get responses.
3. After a task reaches a terminal status (completed, failed, or cancelled) and its keepAlive duration has elapsed, receivers MAY delete the task and its results.
4. Receivers MAY include a pollFrequency value (in milliseconds) in tasks/get responses to suggest polling intervals. Requestors SHOULD respect this value when provided.

​

4.6. Result Retrieval

1. Receivers MUST only return results from tasks/result when the task status is completed.
2. Receivers MUST return an error if tasks/result is called for a task in any other status.
3. Requestors MAY call tasks/result multiple times for the same task while it remains available.

​

4.7. Associating Task-Related Messages

1. All requests, notifications, and responses related to a task MUST include the modelcontextprotocol.io/related-task key in their _meta, with the value set to an object with a taskId matching the associated task ID.
2. For example, an elicitation that a task-augmented tool call depends on MUST share the same related task ID with that tool call’s task.

​

4.8. Task Cancellation

1. When a receiver receives a notifications/cancelled notification for the JSON-RPC request ID of a task-augmented request, the receiver SHOULD immediately move the task to the cancelled status and cease all processing associated with that task.
2. Due to the asynchronous nature of notifications, receivers MAY not cancel task processing instantaneously. Receivers SHOULD make a best-effort attempt to halt execution as quickly as possible.
3. If a notifications/cancelled notification arrives after a task has already reached a terminal status (completed, failed, cancelled, or unknown), receivers SHOULD ignore the notification.
4. After a task reaches cancelled status and its keepAlive duration has elapsed, receivers MAY delete the task and its metadata.
5. Requestors MAY send notifications/cancelled at any time during task execution, including when the task is in input_required status. If a task is cancelled while in input_required status, receivers SHOULD also disregard any pending responses to associated requests.
6. Because notifications do not provide confirmation of receipt, requestors SHOULD continue to poll with tasks/get after sending a cancellation notification to confirm the task has transitioned to cancelled status. If the task does not transition to cancelled within a reasonable timeframe, requestors MAY assume the cancellation was not processed.

​

4.9. Task Listing

1. Receivers SHOULD use cursor-based pagination to limit the number of tasks returned in a single response.
2. Receivers MUST include a nextCursor in the response if more tasks are available.
3. Requestors MUST treat cursors as opaque tokens and not attempt to parse or modify them.
4. If a task is retrievable via tasks/get for a requestor, it MUST be retrievable via tasks/list for that requestor.

​

4.10 Task Deletion

1. Receivers MAY accept or reject delete requests for any task at their discretion.
2. If a receiver accepts a delete request, it SHOULD delete the task and all associated results and metadata.
3. Receivers MAY choose not to support deletion at all, or only support deletion for tasks in certain statuses (e.g., only terminal statuses).
4. Requestors SHOULD delete tasks containing sensitive data promptly rather than relying solely on keepAlive expiration for cleanup.

​

5. Message Flow

​

6. Data Types

​

Task

• taskId: Unique identifier for the task
• keepAlive: Time in milliseconds that results will be kept available after completion
• pollFrequency: Suggested time in milliseconds between status checks
• status: Current state of the task execution

​

Task Status

• submitted: The request has been received and queued for execution
• working: The request is currently being processed
• input_required: The request is waiting on additional input from the requestor
• completed: The request completed successfully and results are available
• failed: The task lifecycle itself encountered an error, unrelated to the associated request logic
• cancelled: The request was cancelled before completion
• unknown: A terminal fallback state for unexpected error conditions when the receiver cannot determine the actual task state

​

Task Metadata

{
  "modelcontextprotocol.io/task": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "keepAlive": 60000
  }
}

• taskId (string, required): Client-generated unique identifier for the task
• keepAlive (number, optional): Requested duration in milliseconds to retain results after completion

​

Task Creation Notification

{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/created",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

​

Task Get Request

{
  taskId: string; // The task identifier to query
}

​

Task Get Response

{
  taskId: string; // The task identifier
  status: TaskStatus; // Current task state
  keepAlive: number | null; // Actual retention duration in milliseconds, null for unlimited
  pollFrequency?: number; // Suggested polling interval in milliseconds
  error?: string; // Error message if status is "failed"
}

​

Task Result Request

{
  taskId: string; // The task identifier to retrieve results for
}

​

Task Result Response

{
  // The structure matches the result type of the original request
  // For example, a tools/call task would return CallToolResult structure
  [key: string]: unknown;
}

​

Task List Request

{
  cursor?: string; // Optional cursor for pagination
}

​

Task List Response

{
  tasks: Array<{
    taskId: string;           // The task identifier
    status: TaskStatus;       // Current task state
    keepAlive: number | null; // Retention duration in milliseconds, null for unlimited
    pollFrequency?: number;   // Suggested polling interval in milliseconds
    error?: string;           // Error message if status is "failed"
  }>;
  nextCursor?: string;        // Cursor for next page, absent if no more results
}

​

Related Task Metadata

{
  "modelcontextprotocol.io/related-task": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

​

7. Error Handling

1. Protocol Errors: Standard JSON-RPC errors for protocol-level issues
2. Task Execution Errors: Errors in the underlying request execution, reported through task status

​

7.1. Protocol Errors

• Invalid or nonexistent taskId in tasks/get, tasks/list, or tasks/result: -32602 (Invalid params)
• Invalid or nonexistent cursor in tasks/list: -32602 (Invalid params)
• Request with a taskId that was already used for a different task (if the receiver validates task ID uniqueness): -32602 (Invalid params)
• Attempting to retrieve result when task is not in completed status: -32602 (Invalid params)
• Internal errors: -32603 (Internal error)

{
  "jsonrpc": "2.0",
  "id": 70,
  "error": {
    "code": -32602,
    "message": "Failed to retrieve task: Task not found"
  }
}

{
  "jsonrpc": "2.0",
  "id": 71,
  "error": {
    "code": -32602,
    "message": "Failed to retrieve task: Task has expired"
  }
}

NOTE: Receivers are not obligated to retain task metadata indefinitely. It is compliant behavior for a receiver to return a “not-found” error if it has purged an expired task.

{
  "jsonrpc": "2.0",
  "id": 72,
  "error": {
    "code": -32602,
    "message": "Cannot retrieve result: Task status is 'working', not 'completed'"
  }
}

{
  "jsonrpc": "2.0",
  "id": 73,
  "error": {
    "code": -32602,
    "message": "Task ID already exists: 786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

​

7.2. Task Execution Errors

{
  taskId: string;
  status: "failed";
  keepAlive: number | null;
  pollFrequency?: number;
  error?: string;  // Description of what went wrong
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "failed",
    "keepAlive": 30000,
    "error": "Tool execution failed: API rate limit exceeded"
  }
}

​

8. Security Considerations

​

8.1. Task Isolation and Access Control

1. Receivers SHOULD scope task IDs to prevent unauthorized access:
   1. Bind tasks to the session that created them (if sessions are supported)
   2. Bind tasks to the authentication context (if authentication is used)
   3. Reject tasks/get, tasks/list, or tasks/result requests for tasks from different sessions or auth contexts
2. Receivers that do not implement session or authentication binding SHOULD document this limitation clearly, as task results may be accessible to any requestor that can guess the task ID.
3. Receivers SHOULD implement rate limiting on:
   1. Task creation to prevent resource exhaustion
   2. Task status polling to prevent denial of service
   3. Task result retrieval attempts
   4. Task listing requests to prevent denial of service

​

8.2. Resource Management

WARNING: Task results may persist longer than the original request execution time. For sensitive operations, requestors should carefully consider the security implications of extended result retention and may want to retrieve results promptly and request shorter keepAlive durations.

1. Receivers SHOULD:
   1. Enforce limits on concurrent tasks per requestor
   2. Enforce maximum keepAlive durations to prevent indefinite resource retention
   3. Clean up expired tasks promptly to free resources
2. Receivers SHOULD:
   1. Document maximum supported keepAlive duration
   2. Document maximum concurrent tasks per requestor
   3. Implement monitoring and alerting for resource usage

​

8.3. Audit and Logging

1. Receivers SHOULD:
   1. Log task creation, completion, and retrieval events for audit purposes
   2. Include session/auth context in logs when available
   3. Monitor for suspicious patterns (e.g., many failed task lookups, excessive polling)
2. Requestors SHOULD:
   1. Log task lifecycle events for debugging and audit purposes
   2. Track task IDs and their associated operations

​

Rationale

​

Design Decision: Generic Task Primitive

​

Design Decision: Metadata-Based Augmentation

// === MCP SDK (Pseudocode based loosely on modelcontextprotocol/typescript-sdk) ===

/**
 * NEW: A request that resolves to a result, either directly or by polling a task.
 */
class PendingRequest<TResult> {
  constructor(readonly protocol: Protocol, readonly result: Promise<TResult>, readonly taskId?: string) {}

  /**
   * Waits for a result, calling onTaskStatus if provided and a task was created.
   */
  async result({ onTaskStatus }): Promise<TResult> => {
    if (!onTaskStatus || !this.taskId) {
      // No task listener or task ID provided, just block for the result
      return await result;
    }

    // Whichever is successful first (or a failure if all fail) is returned.
    return Promise.any([
      result, // Blocks for result
      (async () => {
        // Blocks for a notifications/tasks/created with the provided task ID
        await this.protocol.waitForTask(this.taskId);
        return await taskHandler(this.taskId);
      })(),
    ]);
  }

  /**
   * Encapsulates polling for a result, calling onTaskStatus after querying the task.
   */
  private async taskHandler({ onTaskStatus }): Promise<TResult> => {
    // Poll for completion
    let task: Task;
    do {
      task = await this.protocol.getTask(this.taskId);
      await onTaskStatus(task);
      await sleep(task.pollFrequency ?? DEFAULT_POLLING_INTERNAL);
    } while (!task.isTerminal());

    // Process result
    return await this.protocol.getTaskResult(this.taskId);
  }
}

/**
 * Simplified/partial client session implementation for illustration purposes.
 * Extends a base class it shares with the server.
 */
class Client extends Protocol {
  /**
   * Existing request method, but with most implementation refactored to beginCallTool
   */
  async callTool<TResult>(
    params: CallToolRequest['params'],
    resultSchema: Schema<TResult>,
  ) {
    // Existing request methods can be changed to reuse new methods exposed for
    // separating request/response flows.
    const request = await this.beginCallTool(params, resultSchema);
    return request.result();
  }

  /**
   * NEW: Low-level method that starts a tool call and returns a PendingRequest
   * object for more granular control.
   */
  async beginCallTool<TResult>(
    params: CallToolRequest['params'],
    resultSchema: Schema<TResult>,
  ) {
    const request = await this.beginRequest({ method: 'tools/call', params }, resultSchema, options);
    return request;
  }
}

// === HOST APPLICATION ===

// Begin a tool call with task support
const pending: PendingRequest<CallToolResult> = await client.beginCallTool(
  {
    name: "analyze_dataset",
    arguments: { dataset: "large_file.csv" },
  },
  CallToolResultSchema,
  {
    keepAlive: 3600000,
  },
);

// Client code can assume tasks are supported, and the fallback case can be handled internally
const result = await pending.result({
  onTaskStatus: async (task) => {
    await sendLatestStateSomewhere(task);
  },
});

const result = await client.callTool(
  {
    name: "analyze_dataset",
    arguments: { dataset: "large_file.csv" },
  },
  CallToolResultSchema,
);

​

Design Decision: Client-Generated Task IDs

• If a request times out, the client can safely retry without creating duplicate tasks
• If a connection drops before the response arrives, the client can reconnect and retry
• The server validates task ID uniqueness and returns an error for duplicates, confirming whether the task was created

• Persistent storage for the task ID mapping (typically a simple key-value store)
• Maintaining the mapping for the task’s keepAlive duration
• Handling mapping lookups for task status and result retrieval

​

Design Decision: Task Creation Notification

1. Notifications enable fire-and-forget request processing. The server can accept the request, begin processing it, and send the notification once the task is created, without needing to block the initial request/response cycle. This is particularly important for servers that dispatch work to background systems or queues—they can acknowledge the request immediately and send the notification once the background system confirms task creation.
2. Notifications support the race pattern that enables graceful degradation. Clients can race between waiting for the original request’s response and waiting for the notifications/tasks/created notification. If the server doesn’t support tasks, no notification arrives and the original response wins. If the server does support tasks, the notification typically arrives first (or approximately simultaneously), enabling polling to begin. A synchronous response would force clients to wait for the response before knowing whether to poll or not.
3. Notifications avoid ambiguity with existing protocol semantics. If the initial request response included task metadata and the client then polled for results, it would change the implied meaning of existing notification types:
   1. Progress notifications: The current MCP specification requires that progress notifications reference tokens that “are associated with an in-progress operation.” While “operation” is not formally defined, the implied understanding is that an operation is bounded by a request/response pair—progress notifications stop when the response is sent. With a synchronous response containing task metadata, progress notifications would need to continue while the task executes, expanding the implied meaning of “operation” to include asynchronous tasks that outlive the original request/response cycle. The notification-based approach avoids this semantic expansion by keeping progress notifications tied to the initial request’s lifecycle, while future task-based progress can be cleanly associated via modelcontextprotocol.io/related-task metadata. We recommend that a future SEP clarify the definition of “operation” in the progress specification.
   2. Cancellation semantics: With the notification-based approach, notifications/cancelled clearly targets the original request ID and causes the associated task to move to cancelled status, maintaining a clean separation between request cancellation and task lifecycle management.

• sHTTP without stream support: In environments where either the client or the server does not support SSE streams, notifications cannot be delivered. In such cases, clients may choose to proactively poll with tasks/get using exponential backoff, though this is nonstandard and may result in unnecessary polling attempts if the server doesn’t support tasks.
• Degraded connection scenarios: If the notification is lost in transit, clients should implement reasonable timeout behavior and fall back to the original response.

​

Design Decision: No Capabilities Declaration

​

Alternative Designs Considered

​

Backward Compatibility

• Existing requests work identically with or without task metadata
• Servers that don’t understand tasks process requests normally
• No protocol version negotiation required
• No capability declarations needed

• Clients race between waiting for the original request’s response and waiting for the notifications/tasks/created notification followed by polling
• Whichever completes first (original response or task-based retrieval) is used by the client
• If a server doesn’t support tasks, no notifications/tasks/created is sent, and the original request’s response is used
• If a server supports tasks, the notifications/tasks/created notification is sent, enabling the client to begin polling for results
• This race pattern ensures graceful degradation without requiring capability negotiation or version detection
• Partial support is possible—servers can support tasks on some requests but not others

• Servers can implement task support incrementally, starting with high-value request types
• Clients can opportunistically use tasks where supported
• No coordination required between client and server updates

​

Future Work

​

Push Notifications

• A task completes or fails
• A task reaches a milestone or significant state transition
• A task requires input (complementing the input_required status)

​

Intermediate Results

• Streaming analysis results as they become available
• Reporting completed phases of multi-step operations
• Providing preview data while full processing continues

​

Nested Task Execution

• Create subtasks in response to a parent task reaching a state that requires additional operations
• Communicate subtask requirements to the client, potentially including required tool calls or sampling requests
• Track subtask completion and use subtask results to advance the parent task
• Maintain provenance through task ID hierarchies, showing the relationship between parent and child tasks