Ethora chat platform MCP: apps, users, rooms, AI agents, chat widgets. Hosted or stdio.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
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 website visitors. Required before an embedded widget can answer on an API-created app. Preconditions: the agent was invited into a room of this app with `ethora-agent-invite` (that creates its bot instance). Works in user auth (app update route); falls back to the app-token `/v2/agents/:id/activate` route when an appToken is stored. Requires: an agent already invited into a room of the selected app (`ethora-agent-create` -> `ethora-chat-create` -> `ethora-agent-invite`); the invite creates the bot instance this tool binds as the app's default responder. Auth: user session (owner of the app). Errors: 404 no bot instance for this agent in the app (invite first); 403 not the app owner. Related: `ethora-widget-snippet-get` next, `ethora-bot-instance-list` to inspect.
App to activate the agent for. Defaults to the app from `ethora-app-select`.
Id (or address) of the agent to activate. Get it from `ethora-agent-list` / `ethora-agent-create`.
Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat bound.
Alias for `agentId` - either name is accepted, pass whichever you have.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
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 website visitors. Required before an embedded widget can answer on an API-created app. Preconditions: the agent was invited into a room of this app with `ethora-agent-invite` (that creates its bot instance). Works in user auth (app update route); falls back to the app-token `/v2/agents/:id/activate` route when an appToken is stored. Requires: an agent already invited into a room of the selected app (`ethora-agent-create` -> `ethora-chat-create` -> `ethora-agent-invite`); the invite creates the bot instance this tool binds as the app's default responder. Auth: user session (owner of the app). Errors: 404 no bot instance for this agent in the app (invite first); 403 not the app owner. Related: `ethora-widget-snippet-get` next, `ethora-bot-instance-list` to inspect.
| Argument | Type | Description |
|---|---|---|
| appId | string | App to activate the agent for. Defaults to the app from `ethora-app-select`. |
| agentId | string | Id (or address) of the agent to activate. Get it from `ethora-agent-list` / `ethora-agent-create`. |
| chatJid | string | Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat bound. |
| agentIdOrAddress | string | Alias for `agentId` - either name is accepted, pass whichever you have. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "App to activate the agent for. Defaults to the app from `ethora-app-select`."
},
"agentId": {
"type": "string",
"minLength": 1,
"description": "Id (or address) of the agent to activate. Get it from `ethora-agent-list` / `ethora-agent-create`."
},
"chatJid": {
"type": "string",
"description": "Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat bound."
},
"agentIdOrAddress": {
"type": "string",
"minLength": 1,
"description": "Alias for `agentId` - either name is accepted, pass whichever you have."
}
},
"additionalProperties": false
}Create a reusable AI agent (POST /v2/apps/:appId/agents). Works in user auth mode (the normal hosted mode) or B2B mode; app-token mode is not accepted by the backend. Each agent is a persona - name, avatar, system prompt, LLM config, plus response-gate settings (responseMode, cooldownSec) that control when it speaks in a room. For multi-agent scenarios (two or more personas conversing in one chat) create each one separately, then `ethora-agent-invite` them into the same room. See the `ethora-agents-quickstart` prompt for the end-to-end recipe. To start from a ready-made public agent instead, `ethora-agent-list { visibility: "public" }` then `ethora-agent-clone`. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. The agent belongs to your account (only you can change it) and is homed in that app; it can still be used in your other apps.
| Argument | Type | Description |
|---|---|---|
| name | string | Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching. |
| slug | string | URL-safe slug (auto-generated from name if omitted). |
| appId | string | 24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather than in the token's own app. |
| isRAG | boolean | Enable retrieval-augmented generation from indexed sources. |
| prompt | string | System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how turn-handoff works through the response gate. |
Invite an Agent into a chat room. Multiple agents can coexist in the same room — call this tool once per agent and they will all appear as members able to converse. Lazily creates a per-App BotInstance (an Ethora user with isBot:true) if one does not already exist for (agent, app). Spawns the XMPP client live; no ai-service restart required. For the full multi-agent recipe see the `ethora-agents-quickstart` prompt. Requires: an agent (`ethora-agent-create`) and a room (`ethora-chat-create`) in the selected app.
| Argument | Type | Description |
|---|---|---|
| appId | string | Required in B2B mode unless already selected via ethora-app-select. |
| chatId | string | Mongo Chat _id (preferred when invoking from admin). |
| agentId | string | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| chatJid | string | Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), exactly the `jid` returned by `ethora-chat-create`. Preferred over `chatId`. |
| agentIdOrAddress | string | Either Mongo _id (24 hex chars) or EOA-style address. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "Required in B2B mode unless already selected via ethora-app-select."
},
"chatId": {
"type": "string",
"description": "Mongo Chat _id (preferred when invoking from admin)."
},
"agentId": {
"type": "string",
"minLength": 1,
"description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
},
"chatJid": {
"type": "string",
"description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), exactly the `jid` returned by `ethora-chat-create`. Preferred over `chatId`."
},
"agentIdOrAddress": {
"type": "string",
"minLength": 1,
"description": "Either Mongo _id (24 hex chars) or EOA-style address."
}
},
"additionalProperties": false
}List AI agents (`GET /v2/agents`): by default your own agents plus the public ones. Pass `appId` to list only the agents homed in that app (`GET /v2/apps/:appId/agents`, which needs you to manage the app; B2B tokens always use this form). Agents belong to your account, not to one app, so the same agent can answer in several of your apps. Public agents (e.g. the platform's Support Agent, sample personas) can be tried with `ethora-agent-try` and copied with `ethora-agent-clone`, not edited. Returns agents with ids, names, owner, visibility, categories and config. Auth: user session or B2B token. Errors: 401/403 wrong auth; empty list when nothing matches.
| Argument | Type | Description |
|---|---|---|
| appId | string | Only agents whose home app is this 24-char hex appId. In user auth the selected app is NOT applied by default (agents are account-level); with a B2B token the selected app is used. |
| limit | integer | Page size (max 200). |
| offset | integer | Number of agents to skip, for paging. |
| category | string | Only agents tagged with this category. |
| visibility | string | `mine` = only your own agents, `public` = only public agents (the directory to clone from). Omit for both. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "Only agents whose home app is this 24-char hex appId. In user auth the selected app is NOT applied by default (agents are account-level); with a B2B token the selected app is used."
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Page size (max 200)."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of agents to skip, for paging."
},
"category": {
"enum": [
"customer-support",
"persona",
"entertainment",
"worker"
],
"type": "string",
"description": "Only agents tagged with this category."
},
"visibility": {
"enum": [
"mine",
"public"
],
"type": "string",
"description": "`mine` = only your own agents, `public` = only public agents (the directory to clone from). Omit for both."
}
},
"additionalProperties": false
}Overwrites the fields you pass; previous values are not kept and cannot be restored from the API, so confirm changes to the prompt, name or settings with the user first. Update a saved AI agent (PUT /v2/agents/:agentId). All fields are optional - only what you pass is updated. Common uses: tune the system `prompt` after a test run, switch `responseMode` to control turn-taking in multi-agent rooms, or adjust `cooldownSec`. See `ethora-agents-quickstart` prompt for the end-to-end recipe. Requires: an agent id or address from `ethora-agent-list` or `ethora-agent-create`. Only the agent's owner can update it: a public agent from someone else, including the platform's Support Agent, answers 403, so `ethora-agent-clone` it and update the copy.
| Argument | Type | Description |
|---|---|---|
| name | string | New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary. |
| slug | string | URL-safe slug. |
| isRAG | boolean | Enable RAG retrieval. |
| prompt | string | Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response gate. |
| agentId | string | Mongo _id (24 hex chars) of the agent to update. |
| ragTags | array |
Mint a long-lived, revocable API key for the currently logged-in user. The key is a user token: send it as `Authorization: Bearer <key>` to the hosted MCP endpoint (or set it in the stdio client) to skip `ethora-user-login`. Shown once. Auth: user auth (logged in). Errors: 401 not logged in; 404 on backends without API key support.
| Argument | Type | Description |
|---|---|---|
| name | string | Label to recognise the key later (e.g. `ci-runner`, `claude-desktop`). |
| ttlDays | integer | Lifetime in days. Server default applies when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"description": "Label to recognise the key later (e.g. `ci-runner`, `claude-desktop`)."
},
"ttlDays": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Lifetime in days. Server default applies when omitted."
}
},
"additionalProperties": false
}Create a new Ethora app (tenant) owned by the currently logged-in user. Allocates a fresh 24-char hex `appId` and sets the caller as owner; counts against the owner's plan limit. Returns the new app object including `appId`. The returned app has its credential fields redacted; call `ethora-app-credentials-reveal { appId, confirm: true }` when a snippet needs the appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; 402/403 plan limit reached; 422 invalid `displayName`. Related: server-side provisioning uses `ethora-b2b-app-create`.
| Argument | Type | Description |
|---|---|---|
| displayName* | string | Human-readable app name shown to users in the app picker and on the public landing page. Not required to be unique across accounts. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"displayName"
],
"properties": {
"displayName": {
"type": "string",
"description": "Human-readable app name shown to users in the app picker and on the public landing page. Not required to be unique across accounts."
}
},
"additionalProperties": false
}List all Ethora apps (tenants) owned by the currently logged-in user. Returns an array with `appId` (24-char hex), `displayName`, `domainName`, ownership and bot-status metadata. Credential fields (appSecret, tenantSecret, appToken, passwords) are redacted in the result; call `ethora-app-credentials-reveal { appId, confirm: true }` to reveal an app's appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; empty list if the user owns no apps. Related: feed `appId` into `ethora-app-update` / `ethora-app-select`.
No arguments.
{
"type": "object",
"properties": {}
}Session-only: remembers which app later calls refer to. Changes nothing on the server and can be called again at any time to switch. Set the current app context for this session so app-scoped tools can omit their `appId` argument. On the hosted server the selection is remembered for the signed-in account (24 hours), so a client that opens a new session per call keeps it; `ethora-app-create` selects the new app by itself, and an account with exactly one app has it selected automatically. Stores `currentAppId` and, if given, `appToken` (which defaults the auth mode to app-token unless `authMode` overrides). Auth: none required to set the context. Errors: effectively none — a non-existent `appId` is not validated here; the first app-scoped API call surfaces the 404. Related: pairs with `ethora-auth-mode-set`.
| Argument | Type | Description |
|---|---|---|
| appId* | string | 24-char hex Ethora appId to set as the current context. Get it from `ethora-app-list`, `ethora-app-create`, or a B2B create/provision response. |
| appToken | string | Per-app appToken to store alongside the appId. If provided, the active auth mode switches to app-token (unless `authMode` says otherwise). Secret. |
| authMode | string | Auth mode to keep after selecting the app. Omit to let the mode default to app-token when an `appToken` is given, or stay unchanged otherwise. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"appId"
],
"properties": {
"appId": {
"type": "string",
"description": "24-char hex Ethora appId to set as the current context. Get it from `ethora-app-list`, `ethora-app-create`, or a B2B create/provision response."
},
"appToken": {
"type": "string",
"description": "Per-app appToken to store alongside the appId. If provided, the active auth mode switches to app-token (unless `authMode` says otherwise). Secret."
},
"authMode": {
"enum": [
"app",
"user",
"b2b"
],
"type": "string",
"description": "Auth mode to keep after selecting the app. Omit to let the mode default to app-token when an `appToken` is given, or stay unchanged otherwise."
}
},
"additionalProperties": false
}Overwrites the fields you pass; previous values are not kept and cannot be restored from the API, so confirm changes to the prompt, name or settings with the user first. Update mutable fields on an app the caller owns (displayName, domainName, appTagline, primaryColor, botStatus). Partial update - omitted fields are left unchanged. Requires: an `appId` from `ethora-app-list` or `ethora-app-create`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 validation (e.g. `domainName` taken, `primaryColor` not `#RRGGBB`).
| Argument | Type | Description |
|---|---|---|
| appId | string | 24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| botStatus | string | `on` enables the AI bot for new conversations (requires a configured prompt — see `ethora-bot-update`); `off` disables it. Does not change the bot's configured prompt or sources. |
| appTagline | string | Short tagline shown on the public app landing page. |
| domainName | string | Subdomain to host the web app at. Setting `abcd` makes the web app available at `abcd.ethora.com`. Must be unique across all Ethora apps; lower-case alphanumerics and dashes only. |
| displayName | string | New human-readable app name. Visible in the app picker and on the public landing page. |
Create a new chat room (MUC room) inside an app the caller owns. Every room created this way is listed in the app's rooms (`defaultRooms`); `pinned: true` additionally makes new users auto-join it (existing users are not added), `pinned: false` (default) keeps it opt-in. Returns the new room object including its JID. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 invalid `title`.
| Argument | Type | Description |
|---|---|---|
| appId | string | 24-char hex ObjectId of the app to create the chat room in. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| title* | string | Display name for the new chat room. Visible to all members; not required to be unique within the app. |
| pinned | boolean | If `true`, the room is added to the app's default rooms list — every new user of the app auto-joins it. If `false`, the room exists but users must be added explicitly. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"title"
],
"properties": {
"appId": {
"type": "string",
"description": "24-char hex ObjectId of the app to create the chat room in. Optional — defaults to the app most recently passed to `ethora-app-select`."
},
"title": {
"type": "string",
"description": "Display name for the new chat room. Visible to all members; not required to be unique within the app."
},
"pinned": {
"type": "boolean",
"default": false,
"description": "If `true`, the room is added to the app's default rooms list — every new user of the app auto-joins it. If `false`, the room exists but users must be added explicitly."
}
},
"additionalProperties": false
}Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). Returns `results` with `from`, `nick`, `body`, `ts` (ms) plus a `nextBefore` cursor for older pages. Identify the room by `roomJid` (`${appId}_${chatId}`) or bare `chatId` plus the selected app. Requires: a room in the selected app (`ethora-chat-create`). Auth: user auth (default on the hosted server) or B2B; app-token mode is not accepted. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 502 MAM_READ_FAILED or `mamUnavailable: true` when the deployment has no message archive.
| Argument | Type | Description |
|---|---|---|
| appId | string | 24-char hex appId. Optional when `roomJid` carries it or an app is selected. |
| limit | integer | Maximum number of most-recent messages to return (default 100). |
| before | integer | Pagination cursor: only messages older than this timestamp (ms), from a previous `nextBefore`. |
| chatId | string | Bare chat id. Needs an app: pass `appId` or select one with `ethora-app-select`. |
| roomJid | string | Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`). Either this or `chatId` is required. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "24-char hex appId. Optional when `roomJid` carries it or an app is selected."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Maximum number of most-recent messages to return (default 100)."
},
"before": {
"type": "integer",
"minimum": 0,
"description": "Pagination cursor: only messages older than this timestamp (ms), from a previous `nextBefore`."
},
"chatId": {
"type": "string",
"description": "Bare chat id. Needs an app: pass `appId` or select one with `ethora-app-select`."
},
"roomJid": {
"type": "string",
"description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`). Either this or `chatId` is required."
}
},
"additionalProperties": false
}Send feedback about Ethora to the Ethora team: something that does not work, behaves differently from what the tool description promised, is missing, or is badly documented. It reaches the team directly, so prefer it over guessing or silently giving up when a tool fails. Recent failures in this session (tool, error code, request id) are attached automatically when `includeRecentErrors` is true, which is what makes a report from here more useful than a web form: the team can join it to the server-side log. Works whether or not you are signed in, so a problem that blocks sign-up can still be reported. Do not put credentials, API keys or end-user personal data in `message`; credential-shaped values in the attached context are redacted before sending. Requires: nothing. Auth: none. Works anonymously; when the session is authenticated the report is attributed to that account. Errors: 422 if `message` is shorter than 5 characters or looks like spam; 429 if too many reports were sent from this address.
| Argument | Type | Description |
|---|---|---|
| string | Reply address. Only useful when the session is not signed in; an authenticated report already carries the account, so leave this out unless the user offers an address. | |
| message* | string | What happened, in the user's own words where possible: what was attempted, what was expected, what occurred instead. No credentials or end-user personal data. |
| category | string | What kind of report this is: `bug` (something is broken), `unexpected` (it works but not as described), `feature` (a request), `docs` (a description or guide is wrong or missing), `other`. Defaults to `other`. |
| includeRecentErrors | boolean | Attach this session's last few tool failures (tool name, error code, request id) so the team can trace them. Default true; set false if the report is unrelated to a failure. |
Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends next tool calls + recipes based on current session state. Auth: none required — inspects state, no API calls. Errors: effectively none. Related: pass a recommended recipe id to `ethora-recipe-run`.
| Argument | Type | Description |
|---|---|---|
| goal | string | What you are trying to do: `new-app` (a new chat app: create, brand, rooms, users, where it lives), `in-app-chat` (chat inside your existing product with your own UI and users), `multi-agent-room` (several AI agents in one room, talking to people and each other), `widget` (AI chat widget on a website), `chat-test` (post and read messages), `b2b-bootstrap-ai` (server-side provisioning), `broadcast`, `sources-ingest`, `files-upload`, `bot-manage`, `user-login`. Omit or use `auto` for recommendations inferred from the current session state. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"goal": {
"enum": [
"auto",
"new-app",
"in-app-chat",
"multi-agent-room",
"widget",
"chat-test",
"b2b-bootstrap-ai",
"broadcast",
"sources-ingest",
"files-upload",
"bot-manage",
"user-login"
],
"type": "string",
"description": "What you are trying to do: `new-app` (a new chat app: create, brand, rooms, users, where it lives), `in-app-chat` (chat inside your existing product with your own UI and users), `multi-agent-room` (several AI agents in one room, talking to people and each other), `widget` (AI chat widget on a website), `chat-test` (post and read messages), `b2b-bootstrap-ai` (server-side provisioning), `broadcast`, `sources-ingest`, `files-upload`, `bot-manage`, `user-login`. Omit or use `auto` for recommendations inferred from the current session state."
}
},
"additionalProperties": false
}Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). The message is attributed to the app's broadcast sender (override the shown name with `senderName`). Use it to seed or test a conversation, e.g. right after `ethora-agent-invite`, and set `waitForReplySec` (up to 60) to wait for an AI agent's answer; replies are returned in `replies`. Identify the room by `roomJid` (`${appId}_${chatId}`, exactly what `ethora-chat-create` returns as `jid`) or by the bare `chatId` plus the selected app. Requires: a room in the selected app (`ethora-chat-create`); for `replies`, an agent invited into it (`ethora-agent-invite`). Auth: user auth (the default on the hosted server) or B2B; app-token mode is not accepted by this route. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 422 empty text. Reply detection needs the message archive (MAM) on the deployment; when it is unavailable `replies` is null and `historyUnavailable` is true.
| Argument | Type | Description |
|---|---|---|
| text* | string | Message body to post (1-4000 chars). |
| appId | string | 24-char hex appId. Optional when `roomJid` carries it or an app is selected. |
| chatId | string | Chat id: either the Mongo chat `_id` (as listed by the app's chat list) or the suffix after `${appId}_` in the room JID. Needs an app: pass `appId` or select one with `ethora-app-select`. |
| roomJid | string | Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), as returned by `ethora-chat-create`. Either this or `chatId` is required. |
| senderName | string |
Upload documents (1–5; PDF, text, etc.) into an agent's knowledge base (the one named by `agentId`, else the app's default agent) (app-token / B2B variant of `ethora-source-doc-upload-legacy`). Async - content becomes queryable once indexing finishes; files passed as base64, 50MB max each. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; 413 too large; 422 unsupported document type. Related: `ethora-source-doc-list`, `ethora-source-doc-delete`.
| Argument | Type | Description |
|---|---|---|
| appId | string | 24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| files* | array | 1 to 5 documents to ingest in this call. |
| agentId | string | Agent whose knowledge base gets the content (24-char hex, from `ethora-agent-list` / `ethora-agent-create`). Must be your own agent or one of this app's. Omit to file it under the app's default agent (the one answering its website widget); an app still on the shared Support Agent first gets its own copy of it. |
| agentIdOrAddress | string | Alias for `agentId` - either name is accepted, pass whichever you have. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"files"
],
"properties": {
"appId": {
"type": "string",
"description": "24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"mimeType",
"base64"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Document file name including extension, e.g. `handbook.pdf`."
},
"base64": {
"type": "string",
"minLength": 1,
"description": "Document content, base64-encoded. A `data:...;base64,` prefix is accepted. Max 50MB decoded per file."
},
"mimeType": {
"type": "string",
"minLength": 1,
"description": "MIME type, e.g. `application/pdf`, `text/plain`, `text/markdown`."
}
},
"additionalProperties": false
},
"maxItems": 5,
"minItems": 1,
"description": "1 to 5 documents to ingest in this call."
},
"agentId": {
"type": "string",
"description": "Agent whose knowledge base gets the content (24-char hex, from `ethora-agent-list` / `ethora-agent-create`). Must be your own agent or one of this app's. Omit to file it under the app's default agent (the one answering its website widget); an app still on the shared Support Agent first gets its own copy of it."
},
"agentIdOrAddress": {
"type": "string",
"minLength": 1,
"description": "Alias for `agentId` - either name is accepted, pass whichever you have."
}
},
"additionalProperties": false
}Adds the crawled pages to an agent's knowledge base (the one named by `agentId`, else the app's default agent); existing documents are kept and nothing is deleted. A URL that is already indexed is refused with 409 unless `force: true` re-crawls it. Crawl a website URL and wait for the crawl to finish: enqueues the job, then polls it until it reports `completed` or `failed`. Returns `{ done, status, jobId, polls, durationMs, result }`; `done: false` with a `note` means the budget ran out while the job was still running (it usually finishes server-side anyway). Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth (403 `AGENT_NOT_WRITABLE` when `agentId` is someone else's agent); 400 malformed `url`; 409 already indexed; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side - check with `ethora-source-site-list`, or stop it with `ethora-source-site-crawl-cancel`). Related: `ethora-agent-knowledge-get` shows what the agent can search afterwards.
| Argument | Type | Description |
|---|---|---|
| url* | string | Absolute URL to crawl, e.g. `https://example.com/docs`. |
| appId | string | 24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| force | boolean | Re-crawl a URL that is already indexed and overwrite the stored copy. Without it an already-indexed URL is refused with 409. |
| agentId | string | Agent whose knowledge base gets the content (24-char hex, from `ethora-agent-list` / `ethora-agent-create`). Must be your own agent or one of this app's. Omit to file it under the app's default agent (the one answering its website widget); an app still on the shared Support Agent first gets its own copy of it. |
Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present (booleans like `hasAppJwt` — values never echoed), the selected appId/agentId, and `hosted`/`sessionId` on the hosted (Streamable HTTP) server. Auth: none required. Errors: effectively none. Related: `ethora-doctor` for an active connectivity check.
No arguments.
{
"type": "object",
"properties": {}
}Session-only: changes which tools this connection lists. Touches no account data. Only the core tools are listed by default. Call this to enable another group for this session; the tool list refreshes automatically (tools/list_changed). On the hosted server the enabled groups are remembered for the signed-in account, so a client that opens a new session per call keeps them. Without `group` it returns the catalogue: each group's summary, tool count and whether it is enabled. Groups: keys, session, apps-admin, rooms, agents-admin, sources, widget, users-files, legacy-bot, b2b, wallet; `all` enables everything. Hidden tools are still described by `search` / `fetch`, and each doc names its group. Auth: none. Errors: UNKNOWN_GROUP for a name outside the list.
| Argument | Type | Description |
|---|---|---|
| group | string | Group to enable, or `all`. Omit to list the groups. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"group": {
"enum": [
"keys",
"session",
"apps-admin",
"rooms",
"agents-admin",
"sources",
"widget",
"users-files",
"legacy-bot",
"b2b",
"wallet",
"all"
],
"type": "string",
"description": "Group to enable, or `all`. Omit to list the groups."
}
},
"additionalProperties": false
}Authenticate as an existing Ethora user with email + password. Stores the user session token in this MCP session and unlocks user-auth tools (`ethora-app-list`, `ethora-files-*`, `ethora-wallet-*`). Auth: user-auth mode (`ethora-auth-mode-set` first) and a configured `appJwt`. Errors: 401/403 bad credentials; 404 email not registered; 429 per-IP rate limit — retry with backoff.
| Argument | Type | Description |
|---|---|---|
| email* | string | User's registered email address (RFC 5322). Must match an account created via `ethora-user-register`. |
| password* | string | Plain-text password the user set during registration. Sent over TLS to the Ethora API; never echoed back or logged. |
| apiKeyName | string | Label for the API key when `createApiKey` is true (e.g. `claude-code-laptop`). |
| createApiKey | boolean | When true, also mint a long-lived API key for this user and return it once, so headless clients / agents can reconnect with `Authorization: Bearer <key>` instead of logging in again. Default false. |
| apiKeyTtlDays | integer | Lifetime of the API key in days when `createApiKey` is true. Server default applies when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "User's registered email address (RFC 5322). Must match an account created via `ethora-user-register`."
},
"password": {
"type": "string",
"description": "Plain-text password the user set during registration. Sent over TLS to the Ethora API; never echoed back or logged."
},
"apiKeyName": {
"type": "string",
"description": "Label for the API key when `createApiKey` is true (e.g. `claude-code-laptop`)."
},
"createApiKey": {
"type": "boolean",
"description": "When true, also mint a long-lived API key for this user and return it once, so headless clients / agents can reconnect with `Authorization: Bearer <key>` instead of logging in again. Default false."
},
"apiKeyTtlDays": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Lifetime of the API key in days when `createApiKey` is true. Server default applies when omitted."
}
},
"additionalProperties": false
}Create a new Ethora user account by email + first/last name, then log in and bind the session. A password is generated when omitted and returned once. By default also mints a long-lived API key so an agent can reconnect later with `Authorization: Bearer <key>` (no human step needed). Auth: user-auth mode and a configured `appJwt` (on a hosted server this is preset). Errors: 401 no `appJwt`; 422 email already registered or password shorter than 6 chars; 429 rate limited. Related: bulk provisioning uses `ethora-user-batch-create`.
| Argument | Type | Description |
|---|---|---|
| email* | string | Email address for the new user. Must be RFC-5322 valid and not already registered within this app. No confirmation click is required to log in; the address is used for password reset. |
| lastName* | string | Last name shown in the user's profile. |
| password | string | Password for the account (min 6 chars). Omit to have a strong random password generated and returned once in the result. |
| firstName* | string | First name shown in the user's profile and message attributions across chat rooms and the app UI. |
| apiKeyName | string | Label for the API key (default `mcp-signup`). |
| createApiKey | boolean | Mint a long-lived API key right after signup and return it once. Default true. Set false if you only need this session. |
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 must hold before it answers. No API call; pure generator using this deployment's hosted widget URL and public API base. The widget answers with the app's ACTIVE bot: for API-created apps run `ethora-agent-create` -> `ethora-agent-invite` -> `ethora-agent-activate { agentId, chatJid }` first, otherwise `POST /v2/widget/sessions` returns 422 and the widget stays silent. Requires: an activated agent on the app (`ethora-agent-activate`); without it the widget opens but never answers. Auth: none required (uses the selected app when `appId` is omitted). Errors: effectively none; when no hosted widget is configured the snippet carries a `<WIDGET_URL>` placeholder. The widget's look (colours, texts, launcher) is saved on the app with `ethora-widget-appearance-set` and loads on every embed by itself, so the snippet only needs `data-app-id`; the cosmetic parameters here write attributes into the tag, which then win over the saved look on that site. Related: `ethora-agent-activate`, `ethora-widget-appearance-set`, `ethora-bot-widget-get` (legacy per-app bot only).
| Argument | Type | Description |
|---|---|---|
| appId | string | App the widget belongs to (24-char hex). Defaults to the app from `ethora-app-select`. |
| botId | string | Legacy `data-bot-id` (bot XMPP address); only for old embeds. Prefer `appId`: the backend picks the active agent from the app. |
| locale | string | UI locale (`data-locale`), e.g. `en`, `fr`, `es`. |
| apiBase | string |
Fetch the full text of a documentation section or tool reference entry by the id returned from `search` (e.g. `tool:ethora-app-create`, `doc:auth-map#app-jwt`, `doc:hosted-guide`). Auth: none required. Errors: unknown id.
| Argument | Type | Description |
|---|---|---|
| id* | string | Document id from a `search` result. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Document id from a `search` result."
}
},
"additionalProperties": false
}Search the Ethora documentation and tool reference: auth model (app JWT vs app token vs B2B token vs API keys), hosted-server getting started, chat-component and backend SDK quickstarts, recipes, and a reference entry for every tool with its inputs. Use it for any "how do I ..." question about Ethora before guessing; then call `fetch` with a result id to read the full text. Auth: none required.
| Argument | Type | Description |
|---|---|---|
| query* | string | Free-text query, e.g. 'create an app', 'invite agent to chat', 'api key bearer header'. Empty returns the getting-started guides. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Free-text query, e.g. 'create an app', 'invite agent to chat', 'api key bearer header'. Empty returns the getting-started guides."
}
},
"additionalProperties": false
}| ragTags | array | Optional RAG tag filter — restrict retrieval to sources matching these tags. |
| summary | string | Short bio shown in agent lists. |
| trigger | string | Legacy trigger field. Prefer the newer `responseMode` for new agents. |
| llmModel | string | Model id served by this deployment's AI endpoint; omit for the platform default. `ethora-agent-model-list` returns the supported ids; an unsupported id is rejected with LLM_MODEL_UNSUPPORTED and that list. |
| flowsYaml | string | Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script. |
| categories | array | Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set. |
| visibility | string | 'private' (only invitable inside the owning app) or 'public' (cross-app invitable). |
| cooldownSec | integer | Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking in multi-agent scenarios. |
| isPublished | boolean | Convenience alias for setting visibility='public'. |
| llmProvider | string | Leave empty. The deployment has one AI endpoint (OpenAI-compatible); `openai` and `openai-compatible` are accepted as synonyms, anything else is rejected with LLM_PROVIDER_UNSUPPORTED. |
| botAvatarUrl | string | URL of the avatar image shown next to bot messages. |
| responseMode | string | When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate decides per-message; 'probability' = coin-flip per message using `responseProbability`. |
| botDisplayName | string | Display name used inside the chat UI. Defaults to `name`. |
| greetingMessage | string | Optional message the agent posts when it first joins a room. |
| responseProbability | number | If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"description": "Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching."
},
"slug": {
"type": "string",
"description": "URL-safe slug (auto-generated from name if omitted)."
},
"appId": {
"type": "string",
"description": "24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather than in the token's own app."
},
"isRAG": {
"type": "boolean",
"description": "Enable retrieval-augmented generation from indexed sources."
},
"prompt": {
"type": "string",
"description": "System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how turn-handoff works through the response gate."
},
"ragTags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Optional RAG tag filter — restrict retrieval to sources matching these tags."
},
"summary": {
"type": "string",
"description": "Short bio shown in agent lists."
},
"trigger": {
"enum": [
"any_message",
"/bot"
],
"type": "string",
"description": "Legacy trigger field. Prefer the newer `responseMode` for new agents."
},
"llmModel": {
"type": "string",
"description": "Model id served by this deployment's AI endpoint; omit for the platform default. `ethora-agent-model-list` returns the supported ids; an unsupported id is rejected with LLM_MODEL_UNSUPPORTED and that list."
},
"flowsYaml": {
"type": "string",
"description": "Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script."
},
"categories": {
"type": "array",
"items": {
"enum": [
"customer-support",
"persona",
"entertainment",
"worker"
],
"type": "string"
},
"maxItems": 4,
"description": "Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set."
},
"visibility": {
"enum": [
"private",
"public"
],
"type": "string",
"description": "'private' (only invitable inside the owning app) or 'public' (cross-app invitable)."
},
"cooldownSec": {
"type": "integer",
"minimum": 0,
"description": "Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking in multi-agent scenarios."
},
"isPublished": {
"type": "boolean",
"description": "Convenience alias for setting visibility='public'."
},
"llmProvider": {
"type": "string",
"description": "Leave empty. The deployment has one AI endpoint (OpenAI-compatible); `openai` and `openai-compatible` are accepted as synonyms, anything else is rejected with LLM_PROVIDER_UNSUPPORTED."
},
"botAvatarUrl": {
"type": "string",
"description": "URL of the avatar image shown next to bot messages."
},
"responseMode": {
"enum": [
"always",
"mentioned",
"smart",
"probability"
],
"type": "string",
"description": "When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate decides per-message; 'probability' = coin-flip per message using `responseProbability`."
},
"botDisplayName": {
"type": "string",
"description": "Display name used inside the chat UI. Defaults to `name`."
},
"greetingMessage": {
"type": "string",
"description": "Optional message the agent posts when it first joins a room."
},
"responseProbability": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages."
}
},
"additionalProperties": false
}| RAG tag filter. |
| summary | string | Short bio. |
| trigger | string | Legacy trigger field. Prefer `responseMode`. |
| llmModel | string | LLM model override. |
| flowsYaml | string | Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script. |
| categories | array | Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set. |
| visibility | string | 'private' or 'public' (cross-app invitable). |
| cooldownSec | integer | Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking. |
| isPublished | boolean | Convenience alias for visibility='public'. |
| llmProvider | string | LLM provider override. |
| botAvatarUrl | string | Avatar image URL. |
| responseMode | string | When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbability`. |
| botDisplayName | string | Display name in chat UI. |
| greetingMessage | string | Message the agent posts when it first joins a new room. |
| agentIdOrAddress | string | Alias for `agentId` - either name is accepted, pass whichever you have. |
| responseProbability | number | If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"description": "New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary."
},
"slug": {
"type": "string",
"description": "URL-safe slug."
},
"isRAG": {
"type": "boolean",
"description": "Enable RAG retrieval."
},
"prompt": {
"type": "string",
"description": "Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response gate."
},
"agentId": {
"type": "string",
"minLength": 1,
"description": "Mongo _id (24 hex chars) of the agent to update."
},
"ragTags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "RAG tag filter."
},
"summary": {
"type": "string",
"description": "Short bio."
},
"trigger": {
"enum": [
"any_message",
"/bot"
],
"type": "string",
"description": "Legacy trigger field. Prefer `responseMode`."
},
"llmModel": {
"type": "string",
"description": "LLM model override."
},
"flowsYaml": {
"type": "string",
"description": "Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script."
},
"categories": {
"type": "array",
"items": {
"enum": [
"customer-support",
"persona",
"entertainment",
"worker"
],
"type": "string"
},
"maxItems": 4,
"description": "Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set."
},
"visibility": {
"enum": [
"private",
"public"
],
"type": "string",
"description": "'private' or 'public' (cross-app invitable)."
},
"cooldownSec": {
"type": "integer",
"minimum": 0,
"description": "Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking."
},
"isPublished": {
"type": "boolean",
"description": "Convenience alias for visibility='public'."
},
"llmProvider": {
"type": "string",
"description": "LLM provider override."
},
"botAvatarUrl": {
"type": "string",
"description": "Avatar image URL."
},
"responseMode": {
"enum": [
"always",
"mentioned",
"smart",
"probability"
],
"type": "string",
"description": "When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbability`."
},
"botDisplayName": {
"type": "string",
"description": "Display name in chat UI."
},
"greetingMessage": {
"type": "string",
"description": "Message the agent posts when it first joins a new room."
},
"agentIdOrAddress": {
"type": "string",
"minLength": 1,
"description": "Alias for `agentId` - either name is accepted, pass whichever you have."
},
"responseProbability": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot."
}
},
"additionalProperties": false
}| primaryColor |
| string |
| Primary brand color in hex `#RRGGBB` format (e.g. `#F54927`). Used throughout the app UI. |
| appDescription | string | Deprecated alias for `appTagline`, kept so older callers keep working. Prefer `appTagline`. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`."
},
"botStatus": {
"enum": [
"on",
"off"
],
"type": "string",
"description": "`on` enables the AI bot for new conversations (requires a configured prompt — see `ethora-bot-update`); `off` disables it. Does not change the bot's configured prompt or sources."
},
"appTagline": {
"type": "string",
"description": "Short tagline shown on the public app landing page."
},
"domainName": {
"type": "string",
"description": "Subdomain to host the web app at. Setting `abcd` makes the web app available at `abcd.ethora.com`. Must be unique across all Ethora apps; lower-case alphanumerics and dashes only."
},
"displayName": {
"type": "string",
"description": "New human-readable app name. Visible in the app picker and on the public landing page."
},
"primaryColor": {
"type": "string",
"description": "Primary brand color in hex `#RRGGBB` format (e.g. `#F54927`). Used throughout the app UI."
},
"appDescription": {
"type": "string",
"description": "Deprecated alias for `appTagline`, kept so older callers keep working. Prefer `appTagline`."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"message"
],
"properties": {
"email": {
"type": "string",
"description": "Reply address. Only useful when the session is not signed in; an authenticated report already carries the account, so leave this out unless the user offers an address."
},
"message": {
"type": "string",
"maxLength": 4000,
"minLength": 5,
"description": "What happened, in the user's own words where possible: what was attempted, what was expected, what occurred instead. No credentials or end-user personal data."
},
"category": {
"enum": [
"bug",
"unexpected",
"feature",
"docs",
"other"
],
"type": "string",
"description": "What kind of report this is: `bug` (something is broken), `unexpected` (it works but not as described), `feature` (a request), `docs` (a description or guide is wrong or missing), `other`. Defaults to `other`."
},
"includeRecentErrors": {
"type": "boolean",
"description": "Attach this session's last few tool failures (tool name, error code, request id) so the team can trace them. Default true; set false if the report is unrelated to a failure."
}
},
"additionalProperties": false
}| Display name shown as the message sender (defaults to the app's broadcast sender / app name). |
| waitForReplySec | integer | Seconds to wait for a reply from someone else in the room (an AI agent, typically). 0 (default) returns right after posting. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Message body to post (1-4000 chars)."
},
"appId": {
"type": "string",
"description": "24-char hex appId. Optional when `roomJid` carries it or an app is selected."
},
"chatId": {
"type": "string",
"description": "Chat id: either the Mongo chat `_id` (as listed by the app's chat list) or the suffix after `${appId}_` in the room JID. Needs an app: pass `appId` or select one with `ethora-app-select`."
},
"roomJid": {
"type": "string",
"description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), as returned by `ethora-chat-create`. Either this or `chatId` is required."
},
"senderName": {
"type": "string",
"maxLength": 60,
"description": "Display name shown as the message sender (defaults to the app's broadcast sender / app name)."
},
"waitForReplySec": {
"type": "integer",
"maximum": 60,
"minimum": 0,
"description": "Seconds to wait for a reply from someone else in the room (an AI agent, typically). 0 (default) returns right after posting."
}
},
"additionalProperties": false
}| timeoutMs | integer | How long to poll for the crawl to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls. |
| followLink | boolean | If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care. |
| agentIdOrAddress | string | Alias for `agentId` - either name is accepted, pass whichever you have. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"minLength": 1,
"description": "Absolute URL to crawl, e.g. `https://example.com/docs`."
},
"appId": {
"type": "string",
"description": "24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
},
"force": {
"type": "boolean",
"description": "Re-crawl a URL that is already indexed and overwrite the stored copy. Without it an already-indexed URL is refused with 409."
},
"agentId": {
"type": "string",
"description": "Agent whose knowledge base gets the content (24-char hex, from `ethora-agent-list` / `ethora-agent-create`). Must be your own agent or one of this app's. Omit to file it under the app's default agent (the one answering its website widget); an app still on the shared Support Agent first gets its own copy of it."
},
"timeoutMs": {
"type": "integer",
"maximum": 600000,
"minimum": 1000,
"description": "How long to poll for the crawl to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls."
},
"followLink": {
"type": "boolean",
"description": "If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care."
},
"agentIdOrAddress": {
"type": "string",
"minLength": 1,
"description": "Alias for `agentId` - either name is accepted, pass whichever you have."
}
},
"additionalProperties": false
}| apiKeyTtlDays | integer | API key lifetime in days. Server default applies when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"firstName",
"lastName"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address for the new user. Must be RFC-5322 valid and not already registered within this app. No confirmation click is required to log in; the address is used for password reset."
},
"lastName": {
"type": "string",
"description": "Last name shown in the user's profile."
},
"password": {
"type": "string",
"minLength": 6,
"description": "Password for the account (min 6 chars). Omit to have a strong random password generated and returned once in the result."
},
"firstName": {
"type": "string",
"description": "First name shown in the user's profile and message attributions across chat rooms and the app UI."
},
"apiKeyName": {
"type": "string",
"description": "Label for the API key (default `mcp-signup`)."
},
"createApiKey": {
"type": "boolean",
"description": "Mint a long-lived API key right after signup and return it once. Default true. Set false if you only need this session."
},
"apiKeyTtlDays": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "API key lifetime in days. Server default applies when omitted."
}
},
"additionalProperties": false
}| Override the public API base (`data-api-base`). Defaults to this deployment's public API URL. |
| botName | string | Display name shown in the widget header (`data-bot-name`). Usually leave it out: the widget shows the active agent's name. |
| greeting | string | Greeting shown when the panel opens (`data-greeting-message`). |
| position | string | Launcher corner (`data-position`). |
| botAvatar | string | Avatar image URL shown for the bot (`data-bot-avatar`). |
| widgetUrl | string | Override the widget bundle base URL (the script is `<widgetUrl>/assistant.js`). |
| primaryColor | string | Brand colour for launcher and bubbles (`data-primary-color`), e.g. `#0052CC`. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"appId": {
"type": "string",
"description": "App the widget belongs to (24-char hex). Defaults to the app from `ethora-app-select`."
},
"botId": {
"type": "string",
"description": "Legacy `data-bot-id` (bot XMPP address); only for old embeds. Prefer `appId`: the backend picks the active agent from the app."
},
"locale": {
"type": "string",
"description": "UI locale (`data-locale`), e.g. `en`, `fr`, `es`."
},
"apiBase": {
"type": "string",
"description": "Override the public API base (`data-api-base`). Defaults to this deployment's public API URL."
},
"botName": {
"type": "string",
"description": "Display name shown in the widget header (`data-bot-name`). Usually leave it out: the widget shows the active agent's name."
},
"greeting": {
"type": "string",
"description": "Greeting shown when the panel opens (`data-greeting-message`)."
},
"position": {
"enum": [
"right",
"left"
],
"type": "string",
"description": "Launcher corner (`data-position`)."
},
"botAvatar": {
"type": "string",
"description": "Avatar image URL shown for the bot (`data-bot-avatar`)."
},
"widgetUrl": {
"type": "string",
"description": "Override the widget bundle base URL (the script is `<widgetUrl>/assistant.js`)."
},
"primaryColor": {
"type": "string",
"description": "Brand colour for launcher and bubbles (`data-primary-color`), e.g. `#0052CC`."
}
},
"additionalProperties": false
}