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	array<string>	no	Filter by whether the task is open or closed. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.
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	—
metadata	string	no	A MetadataFilter as JSON, url-encoded. It travels as JSON rather than as key:value pairs because the match is exact and a query string cannot otherwise say whether 3 is the number or the string.
limit	number	no	Results per page. Above the maximum it is clamped; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.

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	—
idempotency_key	string	no	The create's deduplication key, unique within the project and claimed for as long as the task it created exists. The same key with the same body returns that task as it is now (200) instead of creating a second one; with a different body it is 409 IDEMPOTENCY_KEY_REUSED. A create that fails claims no key. Equivalent to the Idempotency-Key header.
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	—

list-task-transitions

List a task's transitions

Arguments

Argument	Type	Required	Description
task_id	string	yes	The task whose transitions are listed.
limit	number	no	Results per page. Above the maximum it is clamped; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.

transition-task

Transition a task

Arguments

Argument	Type	Required	Description
task_id	string	yes	—
transition	string	yes	—
note	string | null	no	—
payload	object	no	Keys shallow-merged over the task's payload under the transition's lock, before the guard reads it, exactly as PATCH merges them; the result must satisfy the payload schema of the version the task is pinned to (TASK_PAYLOAD_INVALID). A refused move writes none of it. On a requires_approval transition the payload is held with the gate and merged when the approval fires the move, so a rejected or expired gate writes nothing.
idempotency_key	string	no	The move's deduplication key, unique within the task and claimed for as long as the task exists. The same key with the same body replays the task as it is now instead of moving it again, whether the move applied or parked an approval; with a different body it is 409 IDEMPOTENCY_KEY_REUSED. Equivalent to the Idempotency-Key header.
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.

migrate-task

Migrate a task to a newer workflow version

Arguments

Argument	Type	Required	Description
task_id	string	yes	The task to migrate.
to_version	number	yes	The workflow version to move the task onto; newer than its current one.
state_map	object	no	Current state name to a state the target version declares. Required only for a state the target lacks; an entry for a state both declare overrides the identity mapping.

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; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.