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	The graph's nodes. Each id is unique and is what edges and nodes.<id> state references name; a node with no incoming edge starts the run.
edges	array<object>	yes	Directed edges between node ids. Every from/to must name a node in nodes, and the graph must be acyclic unless it contains a loop node. A node with several outgoing edges activates every target in parallel. [] for a graph of independent nodes.
state_schema	object | null	no	—
input_schema	object | null	no	—
output_mapping	object | null	no	The shape of a succeeded run's output, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as summary.title builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against { "state": <final run state> }, which includes state.input and state.nodes.<id>. A missing path maps to null; a mapping that throws fails the run. Null (or omitted) keys output by terminal node id. Versioned with the graph; null on update clears it.
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	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.

validate-orchestration

Validate an orchestration graph

Arguments

Argument	Type	Required	Description
nodes	array<object>	no	The graph's nodes. Each id is unique and is what edges and nodes.<id> state references name; a node with no incoming edge starts the run. Checked exactly as create checks them, without persisting.
edges	array<object>	no	Directed edges between node ids. Every from/to must name a node in nodes, and the graph must be acyclic unless it contains a loop node. A node with several outgoing edges activates every target in parallel. Checked exactly as create checks them, without persisting.
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.

list-queue-stats-projects

List the projects with queued orchestration work

Arguments

Argument	Type	Required	Description
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.

get-orchestration

Get an orchestration

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)

update-orchestration

Update an orchestration

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)
name	string	no	—
description	string | null	no	—
nodes	array<object>	no	The graph's nodes. Each id is unique and is what edges and nodes.<id> state references name; a node with no incoming edge starts the run. Replaces the stored list; omitted, the stored nodes are kept and validated against the new edges.
edges	array<object>	no	Directed edges between node ids. Every from/to must name a node in nodes, and the graph must be acyclic unless it contains a loop node. A node with several outgoing edges activates every target in parallel. Replaces the stored list; omitted, the stored edges are kept and validated against the new nodes.
state_schema	object | null	no	—
input_schema	object | null	no	—
output_mapping	object | null	no	The shape of a succeeded run's output, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as summary.title builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against { "state": <final run state> }, which includes state.input and state.nodes.<id>. A missing path maps to null; a mapping that throws fails the run. Null (or omitted) keys output by terminal node id. Versioned with the graph; null on update clears it.
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.
expected_version	any	no	Refuses the write unless the resource is at this version.

delete-orchestration

Delete an orchestration

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)

list-orchestration-versions

List an orchestration's graph versions

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)
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.

get-orchestration-version

Fetch an archived orchestration version

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)
version	number	yes	The archived version number

restore-orchestration-version

Restore an archived orchestration graph

Arguments

Argument	Type	Required	Description
orchestration_id	string	yes	Public ID of the orchestration (orch_...)
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. It is write-only: a run is a record every principal who may read runs can read, and a credential in it is not theirs to see, so it is never returned on one. It also does not outlive the run: reaching a terminal status (succeeded, failed, cancelled or expired) clears it. 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	any	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.
idempotency_key	string	no	Deduplication key, unique within the project, that makes a retry of an ambiguous failure safe. The first request under a key starts the run and answers 201; any later request carrying the same key answers 200 with that same run, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the run record and stays claimed for as long as the record exists, so it never silently expires and lets a second run through. orchestration_id, input, tool_context and metadata are the request the key names: reusing a key with any of them changed is 409 IDEMPOTENCY_KEY_REUSED rather than a replay of a run that does something else. wait is not part of that comparison — it says how the caller waits, not what the run is — so a retry may flip it.
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
project_id	string	no	Narrow the listing to one project (proj_...). A project-scoped key lists its own project without it.
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	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.

cancel-orchestration-run

Cancel an orchestration run

Arguments

Argument	Type	Required	Description
orchestration_run_id	string	yes	Public ID of the run (run_...)

pause-orchestration-run

Pause an orchestration run

Arguments

Argument	Type	Required	Description
orchestration_run_id	string	yes	Public ID of the run (run_...)
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
orchestration_run_id	string	yes	Public ID of the run (run_...)
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

Argument	Type	Required	Description
orchestration_run_id	string	yes	Public ID of the run (run_...)

get-orchestration-run

Get an orchestration run

Arguments

Argument	Type	Required	Description
orchestration_run_id	string	yes	Public ID of the run (run_...)

list-orchestration-run-node-executions

List a run's node executions

Arguments

Argument	Type	Required	Description
orchestration_run_id	string	yes	Public ID of the run (run_...)
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.