# Conversations

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

# Conversations

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

### `list-conversations`

List conversations

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (optional) |
| `actor_id` | `string` | no | Filter by actor ID |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |

### `create-conversation`

Create a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID. Required for JWT auth; omit when using an project key. |
| `status` | `string` | no | Initial conversation status |
| `name` | `string \| null` | no | Optional name for the conversation |
| `actor_id` | `string \| null` | no | Actor ID to associate with this conversation |

### `get-conversation`

Get a conversation by ID

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |

### `update-conversation`

Update a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |
| `status` | `string` | no | New conversation status |
| `name` | `string \| null` | no | New conversation name |

### `delete-conversation`

Delete a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |

### `list-conversation-messages`

List conversation messages

#### Arguments

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

### `add-conversation-message`

Add a message to a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |
| `message` | `string` | yes | Message text content to add to the conversation |
| `role` | `string` | yes | Role of the message sender |
| `actor_id` | `string \| null` | no | Optional actor ID to associate with this message (user identity) |
| `position` | `number` | no | Zero-based position. Defaults to MAX+1 (append). |
| `metadata` | `object \| null` | no | Optional structured metadata to attach to the message (e.g. phone number, channel). Stored as-is and injected into the AI prompt context. |

### `generate-conversation-message`

Generate the next message in a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | — |
| `wait` | `boolean` | no | When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. A `builtin` tool call always waits. |
| `agent_id` | `string` | yes | ID of the agent that will produce the next message. |
| `model` | `string` | no | Optional model override. |
| `stream` | `boolean` | no | If true, stream tokens via SSE. NOT IMPLEMENTED in v1 — returns 501. |
| `tool_context` | `object \| null` | no | Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased and keys are never case-converted, so they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`. |

### `remove-conversation-message`

Remove a message from a conversation

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |
| `document_id` | `string` | yes | Document ID |

### `get-conversation-tags`

Get conversation tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |

### `replace-conversation-tags`

Replace conversation tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |

### `merge-conversation-tags`

Merge conversation tags

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `conversation_id` | `string` | yes | Conversation ID |