Chat MCP Server
Create and execute durable Chat documents — conversations that live in the user's workspace.
|
|
https://api.charmiq.ai/mcp/chatTools
create_chat | |
read_chat | |
delete_chat | |
execute_chat | |
retry_chat |
create_chat, read_chat, and delete_chat are convenience wrappers around the VFS server (create_file with type='chat', read_file, delete_file). If you're already using VFS, you can call those directly — same result.The Execution Flow
create_chatto mint a new Chat document. Returns acharmiq://chat/<id>URI.execute_chat(uri, message, agentIds?)to send the user's first message and run a completion. Both the message and the Charm's response are written to the document.read_chat(uri)any time you want to inspect the current state.Repeat step 2 for follow-up turns. (Optional) delete_chat(uri)when the conversation is done.
agentIds is omitted, the system default Chat agent runs. Otherwise the Charms you name run in sequence — each gets the prior turns as context.Recovering from Consent
execute_chat may fail with mcp/consent-required. The user's message is already in the document; only the Charm's failed turn needs replacing.retry_chat(uri) with the same Chat URI. It replaces the failed Agent turn — your application doesn't have to re-post the user message.Context Dependents
execute_chat accepts context dependents to attach material the Charm should see when answering: documents, folders, uploaded files. Each dependent carries:dependentType | richtext, folder, or asset |
dependentId | {id} portion of the corresponding charmiq:// URI |
list_dir, semantic_search, or by parsing a charmiq:// URI you already have. Folders attach as containers; the Charm sees their contents.Patterns
One Chat per conversation. Don't reuse a Chat document for an unrelated topic — the Charm sees everything above and will let it bleed in. Don't recreate state. A Chat document persists the entire conversation. You never need to re-send earlier turns on follow-ups. Use retry_chatafter consent, notexecute_chat. Re-sending the user message would duplicate it in the document.Discover Agents through the Agent server. list_agentsreturns the IDs to pass intoexecute_chat.
Next Steps
execute_chat.