# Formations

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

# Formations

MCP tools for the Formations module. See the [Formations module docs](/docs/modules/formations) for permissions and data model.

### `validate-formation`

Validate a formation template

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `template` | `object \| string` | no | A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. |
| `parameters` | `object \| null` | no | Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. When provided, the validation result also reports required parameters that are still missing after applying these values. |

### `plan-formation`

Plan a formation deployment

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. |
| `formation_id` | `string` | no | Existing formation ID to compare against. Omit for new formation planning. |
| `template` | `object \| string` | yes | A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. |
| `parameters` | `object \| null` | no | Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. A parameter declared with `use_previous_value: true` may be omitted to reuse its stored value. |

### `list-formations`

List formations

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (required if not using project key auth) |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |

### `create-formation`

Create a new formation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. |
| `name` | `string` | yes | Human-readable name for the formation stack |
| `template` | `object \| string` | yes | A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. |
| `parameters` | `object \| null` | no | Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here. |
| `metadata` | `object \| null` | no | Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`. |

### `get-formation`

Get a specific formation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `formation_id` | `string` | yes | — |

### `update-formation`

Update an formation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `formation_id` | `string` | yes | — |
| `template` | `object \| string` | no | A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. |
| `parameters` | `object \| null` | no | Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here, unless the parameter is declared with `use_previous_value: true`, in which case omitting it reuses the previously stored value. |
| `metadata` | `object \| null` | no | Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`. |

### `delete-formation`

Delete an formation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `formation_id` | `string` | yes | — |

### `list-formation-events`

List formation operation events

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `formation_id` | `string` | yes | — |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |