MCP Tasks Extension (io.modelcontextprotocol/tasks)¶

The Model Context Protocol Tasks extension (io.modelcontextprotocol/tasks) allows MCP clients and servers to promote long-running or interactive multi-round-trip (MRTR) tools/call invocations into durable background tasks that clients can poll, supply interactive input to, or cancel.

Enabling MCP Tasks (MCPTaskConfig)¶

Enable the extension by setting MCPConfig(tasks=True) or passing an explicit MCPTaskConfig instance:

"""Snippet: enabling the MCP Tasks extension."""

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig


def build() -> "Litestar":
    # start-example
    app = Litestar(plugins=[LitestarMCP(MCPConfig(tasks=True))])
    # end-example
    return app

When tasks is enabled (or auto-enabled because litestar-queues QueuePlugin is registered on the application), LitestarMCP advertises "extensions": {"io.modelcontextprotocol/tasks": {}} inside server/discover and initialize capabilities.

MCPTaskConfig Reference¶

Declaring Task-Capable Tools¶

Individual tools declare how they participate in the Tasks extension via @mcp_tool(task=...) / @mcp_tool(task_support=...) or route opt keys (mcp_task / mcp_task_support):

Task State Machine¶

Every TaskRecord in MCPTaskStore progresses through a deterministic lifecycle:

stateDiagram-v2
    [*] --> working: tools/call (resultType = task)
    working --> input_required: MCPInputRequiredResult
    input_required --> working: tasks/update (inputResponses)
    working --> completed: Tool returns result (or isError = true)
    working --> failed: JSONRPCErrorException / unhandled executor crash
    working --> cancelled: tasks/cancel
    input_required --> cancelled: tasks/cancel

• working: Initial status when MCPTaskStore.create() persists the task under mcp-task:{task_id} (or resumed status after all pending inputRequests are answered).
• input_required: Paused state entered when the tool handler returns MCPInputRequiredResult. The serialized task record includes inputRequests describing the required client actions (for example, elicitation/create or sampling/createMessage).
• completed: Terminal state when the tool handler returns a value or a tool-level error (isError: true). The final tool output is embedded under record.result with resultType: "complete".
• failed: Terminal state recorded when a protocol-level JSONRPCErrorException or unrecoverable worker failure occurs. Carries a structured error: {"code": ..., "message": ..., "data": ...} payload.
• cancelled: Terminal state recorded after cooperative cancellation completes via tasks/cancel.

Note: Terminal statuses (completed, failed, and cancelled) are monotonic. Once record.is_terminal() is True, subsequent transition calls are no-ops.

Multi-Round Input Requests (MCPInputRequiredResult)¶

Tools that require human confirmation, form elicitation, or client-side sampling mid-execution return an MCPInputRequiredResult instance and read client responses from get_mcp_request_context():

1. Mid-Task Pause and tasks/update Resumption¶

When a running background task returns MCPInputRequiredResult(input_requests={...}, request_state="..."):

1. MCPHandlerService transitions the TaskRecord in MCPTaskStore to status="input_required", saves input_requests and request_state, and emits a notifications/tasks update.
2. The client inspects inputRequests via tasks/get (or the notification) and submits responses via tasks/update:

   {
     "jsonrpc": "2.0",
     "id": 12,
     "method": "tasks/update",
     "params": {
       "taskId": "8f1d4e9a2c3b4a5d9e8f7a6b5c4d3e2f",
       "inputResponses": {
         "approval": {"action": "accept"}
       }
     }
   }
   

3. MCPTaskStore.update() merges each accepted response key against the outstanding input_requests. If additional keys remain unanswered, the task stays in input_required with the remaining inputRequests.
4. Once all outstanding keys are satisfied, MCPTaskStore.update() transitions the task back to status="working" and resumes the tool handler with context.input_responses and context.request_state populated on get_mcp_request_context().

2. Pre-Task Synchronous Input (task_input_before_start=True)¶

Some tools need to complete an initial elicitation or approval round before allocating a background TaskRecord or enqueuing a job. Set task_input_before_start=True on @mcp_tool (or mcp_task_input_before_start=True in route opt):

"""Task-capable tool that completes an MRTR input round before task creation."""

from litestar import post

from litestar_mcp import MCPInputRequiredResult, get_mcp_request_context, mcp_tool


# start-example
@mcp_tool(
    task_support="required",
    task_input_before_start=True,
)
@post("/reports")
async def publish_report() -> MCPInputRequiredResult | dict[str, str]:
    context = get_mcp_request_context()
    if not context.input_responses:
        return MCPInputRequiredResult(
            input_requests={
                "approval": {
                    "method": "elicitation/create",
                    "params": {"message": "Publish this report?"},
                }
            },
            request_state="integrity-protected-state",
        )
    return {"status": "published"}


# end-example

1. Initial tools/call: Because context.input_responses is None, MCPHandlerService runs the handler synchronously inside the initial HTTP request. Returning MCPInputRequiredResult sends {"resultType": "input_required", "inputRequests": {...}, "requestState": "..."} directly to the caller without creating a task record.
2. Follow-up tools/call: When the client re-invokes tools/call with _meta / inputResponses and requestState populated, context.input_responses is non-empty. MCPHandlerService creates the durable TaskRecord, forwards input_responses and request_state into the task execution context, and returns {"resultType": "task", "taskId": "...", "status": "working", ...}.

Task JSON-RPC Methods & Ownership Isolation¶

All task methods require the caller to advertise extensions["io.modelcontextprotocol/tasks"] (otherwise the server returns JSON-RPC error -32021). Every TaskRecord is bound to context.owner_id (derived from the authenticated principal when authentication middleware is active). A caller with a different owner_id cannot inspect, update, or cancel another principal's task.

SEP-2663 isError: true vs Protocol Error Handling¶

In accordance with the MCP tool error contract (SEP-2663), litestar-mcp distinguishes between application/tool errors (which an LLM can read and recover from) and protocol errors: