# Sessions > MCP tools for the Sessions module. See the [Sessions module docs](/docs/modules/sessions) for permissions and data model. # Sessions MCP tools for the Sessions module. See the [Sessions module docs](/docs/modules/sessions) for permissions and data model. ### `create-session` Create a session #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `agent_id` | `string` | yes | Agent this session belongs to | | `name` | `string` | no | Optional session name | | `actor_id` | `string` | no | Optional public ID of an existing actor to use as the user actor. Actors are created separately (POST /actors); this field only links one. Omit it and the session has no end user, so its generations match no actor-scoped quota. | | `auto_generate` | `boolean` | no | When true, automatically triggers generation after each user message. | | `tool_context` | `object \| null` | no | Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`. | | `inactivity_ttl_seconds` | `number` | no | Number of seconds of inactivity after which the session expires. 0 means the session never expires. | | `message_delay_seconds` | `number \| null` | no | Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. null or absent means no delay (immediate processing). | ### `list-sessions` List sessions #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `agent_id` | `string` | no | Filter by agent public ID | | `actor_id` | `string` | no | Filter by actor public ID | | `status` | `string` | no | Filter by session status (open, closed, or expired) | | `limit` | `number` | no | — | | `offset` | `number` | no | — | ### `get-session` Get a session #### Arguments This tool takes no arguments. ### `update-session` Update a session #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `name` | `string \| null` | no | Session name (set to null to clear) | | `status` | `string` | no | Session status | | `auto_generate` | `boolean` | no | Enable or disable automatic generation after user messages. | | `tool_context` | `object \| null` | no | Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`. | | `inactivity_ttl_seconds` | `number` | no | Number of seconds of inactivity after which the session expires. 0 means the session never expires. Updates the stored TTL; the inactivity clock continues from the last activity timestamp. | | `message_delay_seconds` | `number \| null` | no | Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. Set to null to disable the delay. | ### `delete-session` Delete a session #### Arguments This tool takes no arguments. ### `add-session-message` Add a user message #### Arguments This tool takes no arguments. ### `generate-session-response` Trigger agent generation #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `wait` | `boolean` | no | When omitted or `false` (default), generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. | | `model` | `string` | no | Optional model override | | `tool_context` | `object \| null` | no | Key-value pairs forwarded as `X-Soat-Context-` 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. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`. | ### `submit-session-tool-outputs` Submit tool outputs #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `generation_id` | `string` | yes | The generation ID from the requires_action response | | `tool_outputs` | `array` | yes | — | ### `fork-session` Fork a session #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `fork_at_position` | `number` | no | The parent conversation `position` to branch after. Messages at positions 0..N are carried into the fork. Omit it to branch at the tip (the whole history). | | `agent_id` | `string` | no | Agent the fork runs against. Defaults to the parent session's agent; overriding it is the point of forking — same context, a different agent or agent version. Must belong to the same project as the session being forked. | | `name` | `string` | no | Optional name for the forked session | | `tags` | `object` | no | Optional tags for the forked session | | `tool_context` | `object \| null` | no | Overrides the parent's `tool_context` on the fork. Omit it and the fork inherits the parent's, so the branch is faithful to the run it came from. | ### `list-session-forks` List a session's forks #### Arguments | Argument | Type | Required | Description | | -------- | ---- | -------- | ----------- | | `limit` | `number` | no | — | | `offset` | `number` | no | — | ### `get-session-tags` Get session tags #### Arguments This tool takes no arguments. ### `replace-session-tags` Replace session tags #### Arguments This tool takes no arguments. ### `merge-session-tags` Merge session tags #### Arguments This tool takes no arguments.