Orchestrations
MCP tools for the Orchestrations module. See the Orchestrations module docs for permissions and data model.
create-orchestration
Create an orchestration
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
project_id | string | no | Public ID of the project. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. |
name | string | yes | Human-readable name. |
description | string | null | no | — |
nodes | array<object> | yes | — |
edges | array<object> | yes | — |
state_schema | object | null | no | — |
input_schema | object | null | no | — |
version_label | string | no | Optional tag for the version this create archives, e.g. initial. |
list-orchestrations
List orchestrations
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
project_id | string | no | Filter by project public ID |
limit | number | no | Maximum number of results to return |
offset | number | no | Number of results to skip |
validate-orchestration
Validate an orchestration graph
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
nodes | array<object> | no | — |
edges | array<object> | no | — |
input_schema | object | null | no | Optional JSON Schema for run inputs; its top-level properties seed state. |
get-queue-stats
Get orchestration queue stats
Arguments
This tool takes no arguments.
get-orchestration
Get an orchestration
Arguments
This tool takes no arguments.
update-orchestration
Update an orchestration
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | no | — |
description | string | null | no | — |
nodes | array<object> | no | — |
edges | array<object> | no | — |
state_schema | object | null | no | — |
input_schema | object | null | no | — |
version_label | string | no | Optional tag for the version this write archives, e.g. pre-rewire. Ignored when the write changes no graph field, since no version is archived. |
delete-orchestration
Delete an orchestration
Arguments
This tool takes no arguments.
list-orchestration-versions
List an orchestration's graph versions
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
limit | number | no | Maximum number of results to return |
offset | number | no | Number of results to skip |
get-orchestration-version
Fetch an archived orchestration version
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
version | number | yes | The archived version number |
restore-orchestration-version
Restore an archived orchestration graph
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
version | number | yes | The archived version number |
label | string | no | Optional tag for the version the restore creates. Defaults to restored from v<version>. |
start-orchestration-run
Start an orchestration run
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
orchestration_id | string | yes | Orchestration to run (orch_...). |
input | object | no | Initial state for the run (merged with orchestration defaults). |
tool_context | object | no | Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call made by an agent node of this run — including the agents of any child run a loop or sub_orchestration node starts. The header name is X-Soat-Context- plus the key verbatim; no character is re-cased. The bag is stored on the run and re-read on every step, so it survives an awaiting_input pause, a sleeping wait, a background worker drive and a crash redrive. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with 400 INVALID_TOOL_CONTEXT_KEY and no run is created. The reserved identity keys (session_id, actor_id, actor_external_id) are stripped at generation time — a caller cannot address them from here. |
metadata | object | no | Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read. The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own input and accumulated state) lives in its own top-level field and cannot be written from here. It is not merged into run state: no graph node sees it, and an input_schema never has to tolerate it — which is what makes it the place for an infrastructural label, rather than input. Keys are never transformed. It is not inherited by the child runs a loop or sub_orchestration node starts; each child carries whatever the graph gives it, which today is nothing. |
wait | boolean | no | When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background. |
list-orchestration-runs
List orchestration runs
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
orchestration_id | string | no | Filter by orchestration public ID (orch_...) |
parent_orchestration_run_id | string | no | Filter to the runs one specific parent run's loop / sub_orchestration nodes started (run_...). This is how a caller holding a parent names the individual children behind its usage. |
nested | boolean | no | Filter by whether the run was started by another run. false returns only the runs a caller started (no parent), which is the set to sum usage over; true returns only the runs a loop / sub_orchestration node started, across every parent. Omit to return both. Contradicting parent_orchestration_run_id with nested=false is a 400; any value other than true or false is a 400. |
status | array<string> | no | Filter by run status. Repeat the parameter to OR values — status=queued&status=running&status=sleeping&status=awaiting_input is the set still driving, which is how a caller finds live work without paging every run the project ever started. There is no non_terminal shorthand on purpose: which statuses count as live is the caller's policy. A value outside the enum, empty string included, is a 400. |
limit | number | no | Maximum number of results to return |
offset | number | no | Number of results to skip |
cancel-orchestration-run
Cancel an orchestration run
Arguments
This tool takes no arguments.
pause-orchestration-run
Pause an orchestration run
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
reason | string | no | Why the run is being paused, surfaced on the parked run's required_action.reason and on pause_reason. |
submit-human-input
Submit human input
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
node_id | string | yes | ID of the human node to satisfy. |
output | object | no | Output/response provided by the human reviewer. |
resume-orchestration-run
Resume an orchestration run
Arguments
This tool takes no arguments.
get-orchestration-run
Get an orchestration run
Arguments
This tool takes no arguments.