The MCP Tasks extension (io.modelcontextprotocol/tasks) for the modern (2026-07-28) protocol era.

Specification: https://modelcontextprotocol.io/extensions/tasks and https://github.com/modelcontextprotocol/ext-tasks (schema 2026-07-28). For legacy-era (2025-11-25) tasks see the frozen ConduitMcp.Tasks.

Enabling

config :conduit_mcp, :ext_tasks, true

# or, with options:
config :conduit_mcp, :ext_tasks,
  store: MyApp.TaskStore,        # default ConduitMcp.Ext.Tasks.EtsStore
  janitor: [interval: 30_000],   # Session.Janitor options, or false
  max_rows: 10_000,              # row cap passed to create/2, or :infinity
  notifier: MyApp.TaskNotifier   # default ConduitMcp.Ext.Tasks.ListenNotifier; nil for none

The value is validated when :conduit_mcp starts. When enabled, the application starts ConduitMcp.Ext.Tasks.EtsStore.Owner (default store only) and a ConduitMcp.Session.Janitor named ConduitMcp.Ext.Tasks.Janitor that calls the store's cleanup/1 (TTL expiry; janitor: [ttl: ...] is the age at which terminal tasks without a TTL are evicted, default one hour), and server/discover advertises capabilities.extensions["io.modelcontextprotocol/tasks"].

Returning a task

A tools/call callback (ConduitMcp.Server.handle_call_tool/3, a DSL handle, a ConduitMcp.Component.execute/2) returns {:task, attrs}:

def handle_call_tool(_conn, "build", %{"ref" => ref}) do
  {:task,
   ttl_ms: :timer.minutes(30),
   poll_interval_ms: 2_000,
   status_message: "Queued",
   start: fn task_id -> MyApp.Builds.enqueue(task_id, ref) end}
end

attrs (keyword list or atom-keyed map), all optional:

• :ttl_ms — lifetime from creation (default one hour); nil means unlimited.
• :poll_interval_ms — suggested polling interval (positive integer).
• :status_message — initial status message.
• :start — fn task_id -> ... end, called once the task is stored. This is where the work starts: spawn it (a Task under your supervisor, an Oban job, a message to a GenServer) and return; the request is waiting. If it raises, the task is failed with -32603.

The library then requires that the client declared the extension in this request's io.modelcontextprotocol/clientCapabilities.extensions (otherwise -32021 with data.requiredCapabilities, HTTP 400), stores the task before answering, calls :start, and answers with a CreateTaskResult (resultType: "task"). The task is owned by the request's principal (ConduitMcp.Principal.id/1): tasks/get, tasks/update and tasks/cancel from any other principal answer "Task not found". Unauthenticated tasks are owned by nil; their id is then their only protection (32 random bytes).

Only tools/call may return a task. From any other callback, on the legacy era, or with the extension disabled, {:task, _} is logged and answered with -32603.

Driving a task from the worker

The worker reports through complete/2, fail/2, require_input/3 and progress/2, and reads the task with status/1 (or cancelled?/1). These address the task by id alone: the id is the capability, so keep it out of logs.

def perform(%{args: %{"task_id" => id, "ref" => ref}}) do
  :ok = ConduitMcp.Ext.Tasks.progress(id, "Building")
  result = MyApp.Builds.run(ref)
  ConduitMcp.Ext.Tasks.complete(id, %{"content" => [%{"type" => "text", "text" => result}]})
end

complete/2 takes what the tool would have returned synchronously (a CallToolResult map, isError: true included). fail/2 is for JSON-RPC errors only.

Input mid-flight: require_input/3 moves the task to input_required with MRTR input requests (built with ConduitMcp.MRTR.elicit/2); the client reads them with tasks/get and answers with tasks/update. Once every outstanding key is answered the task returns to working and the answers are in status/1's input_responses. Each key must be unique over the task's lifetime. Poll status/1, or configure a notifier to be told.

Cancellation is cooperative: tasks/cancel moves a non-terminal task to cancelled (after which complete/2/fail/2 return {:error, :terminal}); the worker should check cancelled?/1 and stop.

Terminal states — completed, failed, cancelled — are final.

Status notifications

Every change is handed to the configured ConduitMcp.Ext.Tasks.Notifier. The default, ConduitMcp.Ext.Tasks.ListenNotifier, sends it as notifications/tasks (the full task state, to_wire/1) to the subscriptions/listen streams that named the task in their taskIds filter, and only to those whose principal owns the task (SV-1; see ConduitMcp.Subscriptions.Filter). A custom notifier replaces it; notifier: nil turns notifications off.