Step by step
Connect and identify
A person pastes the personal connector URL from Account, AI Assistants. An agent with no account connects to the open endpoint and calls ethora-user-register { email, firstName, lastName }, receiving a generated password, an API key and a connectorUrl once. ethora-status should report authMode: user.
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp/k/<your API key> claude mcp list
Create the app and make it current
ethora-app-create { displayName } allocates a 24-character appId, sets you as owner and counts against your plan limit. Follow with ethora-app-select { appId } so the room and agent tools can omit appId.
Add rooms
ethora-app-create-chat { title, pinned } creates a group room and returns its JID, appId_chatId. With pinned: true every new user auto-joins it (existing users are not added); the default keeps it opt-in. ethora-app-get-default-rooms lists the selected app’s rooms.
Create an agent and put it in a room
ethora-agents-create-v2 { name, prompt, greetingMessage } defines the persona. ethora-agent-invite-to-chat { agentIdOrAddress, chatJid } spawns its bot instance live in the room. Test it with ethora-chats-message-v2 { text, roomJid, waitForReplySec: 45 }; the answer comes back in replies.
Activate it and embed the widget
ethora-agents-activate-v2 { agentId, chatJid } makes the agent the app’s default responder; on an API-created app the widget stays silent until then. ethora-widget-embed-snippet { botName, primaryColor, greeting } returns the <script> tag for your site.
You: Activate Desk Assistant for the widget and give me the embed code in navy.
Assistant: ethora-agents-activate-v2 { agentId, chatJid } ... botStatus on.
ethora-widget-embed-snippet { botName: "Desk Assistant", primaryColor: "#1F3A5F" } ...
<script id="chat-content-assistant" src="https://widget.<your domain>/assistant.js" data-app-id="<appId>" data-bot-name="Desk Assistant" defer></script>The tools this uses
Names and descriptions come from the server’s own tool list. Read-only tools are safe to auto-approve; destructive ones make your client ask first. Full reference.
| Tool | Name | What it does | Access |
|---|---|---|---|
| Register Account | ethora-user-register | Create a new Ethora user account by email + first/last name, then log in and bind the session. | write |
| Log In | ethora-user-login | Authenticate as an existing Ethora user with email + password. | write |
| Create App | ethora-app-create | Create a new Ethora app (tenant) owned by the currently logged-in user. | write |
| Select App | ethora-app-select | Set the current app context for this session so app-scoped tools can omit their appId argument. | write |
| Create Chat Room | ethora-app-create-chat | Create a new chat room (MUC room) inside an app the caller owns. | write |
| Get Default Rooms | ethora-app-get-default-rooms | List the default chat rooms (MUC rooms) of the currently selected Ethora app - every new user auto-joins these. | read-only |
| Create Agent | ethora-agents-create-v2 | Create a reusable AI agent (POST /v2/apps/:appId/agents). | write |
| Invite Agent to Chat | ethora-agent-invite-to-chat | Invite an Agent into a chat room. | write |
| Send Chat Message | ethora-chats-message-v2 | Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). | write |
| Activate Agent for Widget | ethora-agents-activate-v2 | Make an agent the app’s ACTIVE widget bot: sets App.defaultBotInstanceId (and botStatus: on), which is what POST /v2/widget/sessions uses to decide who answers... | write |
| Widget Embed Snippet | ethora-widget-embed-snippet | Generate the <script> tag that embeds the Ethora AI chat widget (the floating launcher + chat panel that website visitors use) for an app, plus the prerequisites that... | read-only |
| Batch Create Users | ethora-users-batch-create-v2 | Provision many Ethora users (1-100) in one asynchronous batch job - the bulk equivalent of ethora-user-register. | write |
A clinic front desk in one prompt
“Create an app called Riverside Dental Desk with a Front desk room every new user joins. Create an agent called Desk Assistant for opening hours, accepted insurance plans and booking, put it in Front desk and test it. Then activate it for the widget and give me the snippet in navy.”
ethora-app-create{ displayName: "Riverside Dental Desk" }ethora-app-select{ appId: "66f0c2a9b1d4e7f0a3c5d8e1" }ethora-app-create-chat{ title: "Front desk", pinned: true }ethora-agents-create-v2{ name: "Desk Assistant", prompt: "Front desk of a dental practice. Answer questions on opening hours, insurance plans and booking, briefly.", greetingMessage: "Hello, how can I help?" }ethora-agent-invite-to-chat{ agentIdOrAddress: "66f0c3f1a2b3c4d5e6f70123", chatJid: "66f0c2a9b1d4e7f0a3c5d8e1_frontdesk" }ethora-chats-message-v2{ text: "Are you open on Saturdays?", roomJid: "66f0c2a9b1d4e7f0a3c5d8e1_frontdesk", waitForReplySec: 45 }ethora-agents-activate-v2{ agentId: "66f0c3f1a2b3c4d5e6f70123", chatJid: "66f0c2a9b1d4e7f0a3c5d8e1_frontdesk" }ethora-widget-embed-snippet{ botName: "Desk Assistant", primaryColor: "#1F3A5F" }
An app with a room, an agent answering in it, and a script tag that puts the same agent on the clinic website.
Good to know
- Room JIDs are
appId_chatId; every room tool accepts the JID or the barechatIdonce the app is selected. ethora-app-selectdoes not validate the id; a wrongappIdsurfaces as a 404 on the first app-scoped call.ethora-agents-create-v2works in the hosted user session or B2B mode, never app-token mode.- Skip
ethora-agents-activate-v2and the widget session endpoint returns 422; the widget stays silent. - End users sign up through your app, the SDKs or the widget;
ethora-users-batch-create-v2(up to 100 per job) needs B2B auth. ethora-app-deleteandethora-app-delete-chatare irreversible and flagged destructive.
