# Orchestrations

> MCP tools for the Orchestrations module. See the [Orchestrations module docs](/docs/modules/orchestrations) for permissions and data model.

# Orchestrations

MCP tools for the Orchestrations module. See the [Orchestrations module docs](/docs/modules/orchestrations) 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.