Tasks

MCP tools for the Tasks module. See the Tasks module docs for permissions and data model.

list-tasks

List tasks

Arguments

Argument	Type	Required	Description
project_id	string	no	—
workflow_id	string	no	—
state	string	no	—
status	string	no	—
automation_status	array<string>	no	Filter by the current state's dispatch status. Repeat the parameter to OR values. none selects the tasks whose automation_status is null — the ones that never entered a state with an automation. It is a value a task really holds, so it is a value of the filter too; the parameter's own absence already means "every task". A value outside the enum, empty string included, is a 400.
assignee	string	no	—
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.

create-task

Create a task

Arguments

Argument	Type	Required	Description
project_id	string	no	—
workflow_id	string	yes	—
title	string	yes	—
payload	object	no	—
assignee	string | null	no	—
state	string	no	Name of a declared workflow state to create the task in directly, instead of the workflow's initial state. Must name a state declared on the workflow, or the request is rejected with TASK_STATE_NOT_FOUND (400). Defaults to the initial state.
tool_context	object	no	Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call made by this task's automation dispatches — the agent generations a state's on_enter starts, and the agent nodes of any orchestration run it starts. The header name is X-Soat-Context- plus the key verbatim; no character is re-cased. Creation is the task's first move, so this is the bag the entry state's on_enter runs with. Each transition may replace it (see TransitionTaskRequest.tool_context). The reserved identity keys (session_id, actor_id, actor_external_id) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with INVALID_TOOL_CONTEXT_KEY (400). Write-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.
metadata	any	no	Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own). The bag is caller-owned and no key is reserved: everything the engine decides about a task (state, status, workflow_version, last_result, active_dispatch, the automation fields) is a field of its own and cannot be written from here. Prefer this over payload for anything that is not task data: payload is read by every guard as task.payload and may be written by the workflow's declared payload_writes, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with 400 VALIDATION_FAILED and no task is created.

get-task

Get a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—

update-task

Update a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—
title	string	no	—
payload	object	no	Partial payload, shallow-merged over the existing payload. Omitted keys are preserved; provided keys overwrite. The merged result must satisfy the workflow's payload_schema.
assignee	string | null	no	—

delete-task

Delete a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—

transition-task

Transition a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—
transition	string	yes	—
note	string | null	no	—
tool_context	object	no	Caller context for the automation dispatches the task makes from here on, forwarded as X-Soat-Context-<key> headers on their tool calls. Supplying it replaces the task's stored bag wholesale; omitting it keeps the current one, so the context follows whoever last moved the task and survives every move that does not speak about it — including an approval gate, a retry, and an automation hop. Send an empty object to clear it without closing the task. The reserved identity keys (session_id, actor_id, actor_external_id) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with INVALID_TOOL_CONTEXT_KEY (400). Write-only: never returned by a task read, and cleared when the transition closes the task.

pause-task

Pause a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—
reason	string	no	Why the task is being paused, surfaced on pause_reason.

resume-task

Resume a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—

get-task-history

Get task history

Arguments

Argument	Type	Required	Description
task_id	string	yes	—
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.