# Collections MCP Tools

> The MCP tools the SOAT server exposes for the Collections module, with the arguments each tool takes.

# Collections

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

### `list-collections`

List collections

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project public ID (proj_ prefix) |
| `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-collection`

Create a collection

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project the collection belongs to. Optional for a project-scoped API key, which supplies it. |
| `name` | `string` | yes | Unique within the project. |
| `schema` | `object \| null` | no | A JSON Schema every item's `data` must satisfy, stored as written. `null` removes it. |

### `get-collection`

Get a collection

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |

### `update-collection`

Update a collection

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `name` | `string` | no | Unique within the project. |
| `schema` | `object \| null` | no | A JSON Schema every item's `data` must satisfy, stored as written. `null` removes it. |

### `delete-collection`

Delete a collection

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |

### `list-collection-items`

List items

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `data` | `string` | no | A `StructuredFilter` over an item's `data`, as JSON, url-encoded. Equality and `in` are answered by an index; a range is evaluated on the rows the other conditions leave. |
| `tags` | `array` | no | Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value. |
| `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`. |

### `get-collection-item`

Get an item

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |

### `put-collection-item`

Create or replace an item

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |
| `data` | `object` | yes | The item's JSON object, at most 64 KB serialized. Stored as `jsonb`, so key order is not kept. |
| `tags` | `any` | no | Replaces the item's tags; `null` clears them. |
| `expected_version` | `any` | no | Refuses the write unless the item is at this version. |

### `update-collection-item`

Update an item

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |
| `data` | `any` | no | The merge patch applied to the item's `data`. |
| `tags` | `any` | no | Replaces the item's tags; `null` clears them. |
| `expected_version` | `any` | no | Refuses the write unless the item is at this version. |

### `delete-collection-item`

Delete an item

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |

### `get-collection-item-tags`

Get item tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |

### `replace-collection-item-tags`

Replace item tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |

### `merge-collection-item-tags`

Merge item tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `collection_id` | `string` | yes | The collection's public ID (coll_ prefix). |
| `key` | `string` | yes | The item's key, unique in its collection: 1–256 letters, digits and `. _ : @ -`, starting with a letter or digit. |
