# Chats

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

# Chats

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

### `create-chat`

Create a chat

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `ai_provider_id` | `string` | no | Public ID of the AI provider to pin. Optional: omit it to inherit the project's `default_model_route_id`, which gives the chat provider failover. Omitting it returns `400` when the project has no default, and cannot be combined with `model` — each route target names its own. |
| `project_id` | `string` | no | Public ID of the project. Required when the user belongs to multiple projects and no project key is used. |
| `name` | `string` | no | Optional human-readable name |
| `instructions` | `string` | no | Optional system message applied to all completions on this chat |
| `model` | `string` | no | Optional default model override |

### `list-chats`

List chats

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project public ID to filter by |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |

### `get-chat`

Get a chat

#### Arguments

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

### `delete-chat`

Delete a chat

#### Arguments

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

### `create-chat-completion`

Create a chat completion

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `ai_provider_id` | `string` | no | Public ID of the AI provider to run the completion against. Mutually exclusive with `chat_id`; exactly one of the two is required. |
| `chat_id` | `string` | no | Public ID of a stored chat supplying the provider, model and instructions. Mutually exclusive with `ai_provider_id`; exactly one of the two is required. |
| `model` | `string` | no | Model identifier. Overrides the provider's `default_model`, or the chat's `model`, when specified. |
| `instructions` | `string` | no | System instructions for this call. Sent to the provider as its `instructions` argument rather than as a message, which is the only place the AI SDK accepts system content (`allowSystemInMessages` defaults to false). This field is the only channel — a `role: "system"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, this replaces the chat's stored `instructions` for this call only; the stored value applies when the request carries none, and the two are never merged. |
| `messages` | `array<object>` | yes | Ordered list of chat messages |
| `stream` | `boolean` | no | When `true` the response is an SSE stream of delta chunks. When `false` (default) a single JSON object is returned. |