tasks

Wire models for the Tasks extension (io.modelcontextprotocol/tasks, SEP-2663).

SEP-2663 (https://modelcontextprotocol.io/seps/2663-tasks-extension.md) is an opt-in extension, wire-incompatible with the 2025-11-25 in-core Tasks design that still ships (types-only) in mcp_types. This module therefore defines its own SEP-2663-shaped models rather than reusing mcp_types.{Task, CreateTaskResult, ...}.

Both sides of the wire share these shapes: the server runtime (mcp.server.tasks) serves them, and client code sends the typed tasks/* request wrappers and parses tasks/get responses with GetTaskResult. The module depends only on mcp_types and pydantic.

EXTENSION_ID module-attribute

EXTENSION_ID = 'io.modelcontextprotocol/tasks'

The Tasks extension identifier (SEP-2663).

TaskStatus module-attribute

TaskStatus = Literal[
    "working",
    "input_required",
    "completed",
    "failed",
    "cancelled",
]

SEP-2663 task statuses.

Task

Bases: _CarriesTtlMs, _TasksModel

SEP-2663 task snapshot (note the *Ms field names, unlike the 2025 design).

Source code in src/mcp/shared/tasks.py

class Task(_CarriesTtlMs, _TasksModel):
    """SEP-2663 task snapshot (note the `*Ms` field names, unlike the 2025 design)."""

    task_id: str
    status: TaskStatus
    status_message: str | None = None
    created_at: str
    last_updated_at: str
    ttl_ms: int | None = None
    poll_interval_ms: int | None = None

CreateTaskResult

Bases: _CarriesTtlMs, Result

Result & Task flat, discriminated by result_type: "task" (SEP-2663).

Inherits Result's camelCase alias generator, so snake_case fields serialize to resultType/taskId/ttlMs/... on the wire.

Source code in src/mcp/shared/tasks.py

class CreateTaskResult(_CarriesTtlMs, Result):
    """`Result & Task` flat, discriminated by `result_type: "task"` (SEP-2663).

    Inherits `Result`'s camelCase alias generator, so snake_case fields serialize
    to `resultType`/`taskId`/`ttlMs`/... on the wire.
    """

    result_type: Literal["task"] = "task"
    task_id: str
    status: TaskStatus
    status_message: str | None = None
    created_at: str
    last_updated_at: str
    ttl_ms: int | None = None
    poll_interval_ms: int | None = None

GetTaskRequest

Bases: Request[GetTaskRequestParams, Literal['tasks/get']]

SEP-2663 tasks/get request, typed for client-side send_request.

Source code in src/mcp/shared/tasks.py

class GetTaskRequest(Request[GetTaskRequestParams, Literal["tasks/get"]]):
    """SEP-2663 `tasks/get` request, typed for client-side `send_request`."""

    method: Literal["tasks/get"] = "tasks/get"
    params: GetTaskRequestParams

CancelTaskRequest

Bases: Request[CancelTaskRequestParams, Literal['tasks/cancel']]

SEP-2663 tasks/cancel request, typed for client-side send_request.

Source code in src/mcp/shared/tasks.py

class CancelTaskRequest(Request[CancelTaskRequestParams, Literal["tasks/cancel"]]):
    """SEP-2663 `tasks/cancel` request, typed for client-side `send_request`."""

    method: Literal["tasks/cancel"] = "tasks/cancel"
    params: CancelTaskRequestParams

UpdateTaskRequest

Bases: Request[UpdateTaskRequestParams, Literal['tasks/update']]

SEP-2663 tasks/update request, typed for client-side send_request.

Source code in src/mcp/shared/tasks.py

class UpdateTaskRequest(Request[UpdateTaskRequestParams, Literal["tasks/update"]]):
    """SEP-2663 `tasks/update` request, typed for client-side `send_request`."""

    method: Literal["tasks/update"] = "tasks/update"
    params: UpdateTaskRequestParams

GetTaskResult

Bases: Task

SEP-2663 tasks/get response: the task snapshot with its outcome inlined.

A lenient client-side parse model: result is set when the task completed (even a tool result with isError: true), error (the JSON-RPC error dict) when it failed, and both stay None for non-terminal statuses.

Source code in src/mcp/shared/tasks.py

class GetTaskResult(Task):
    """SEP-2663 `tasks/get` response: the task snapshot with its outcome inlined.

    A lenient client-side parse model: `result` is set when the task `completed`
    (even a tool result with `isError: true`), `error` (the JSON-RPC error dict)
    when it `failed`, and both stay `None` for non-terminal statuses.
    """

    result_type: str = "complete"
    result: dict[str, Any] | None = None
    error: dict[str, Any] | None = None