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.

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.

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.

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.

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.

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.

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.

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.

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.

Generate the 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).

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.