Conversations

MCP tools for the Conversations module. See the Conversations module docs 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
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	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
retrieval	string | null	no	Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval.

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
retrieval	string | null	no	Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval. Switching it on embeds the turns already in the conversation, so the whole conversation becomes retrievable rather than only what is said next.

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	any	no	Caller-owned annotations on the message (e.g. a phone number, a channel), stored as sent and returned verbatim. The platform does not read the bag, so nothing in it reaches the model: a value the model should see belongs in message.

generate-conversation-message

Generate the next message in a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	—
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