Set the Ethora API URL and credentials for this MCP session. Stores values in memory only; each call merges with omitted fields kept. Alternative to env vars (ETHORA_API_URL / ETHORA_APP_JWT / ETHORA_APP_TOKEN / ETHORA_B2B_TOKEN). On a hosted server apiUrl is fixed and cannot be changed; credentials are per session. Auth: none required — this establishes auth material. Errors: only if a value is structurally invalid. Follow with an ethora-auth-use-* tool to pick the active mode.

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-run-recipe.

Execute a built-in recipe — an ordered sequence of this server's own tool calls — by id. Recipes capture common flows (B2B bootstrap, broadcast, sources ingest). Use dryRun: true to preview resolved steps. Omit recipeId to list runnable recipes for a goal. Requires: the inputs the chosen recipe lists; call without recipeId first to see the recipes and their required inputs. Auth: depends on the recipe's steps — configure those first (see ethora-help). Errors: stops at the first failing step and returns the partial log; a missing required vars entry fails fast before any step runs.

Diagnose the session: validate the config is internally consistent for the active auth mode and ping the Ethora API (GET /v1/ping). Returns { state, checks, ping, suggestions }. Auth: none required; report is tailored to whatever credentials are set. Errors: rarely throws — instead returns suggestions and a ping.ok: false block when the API is unreachable.

Switch this session's active auth mode to app-token, so subsequent app-scoped calls authenticate with the configured appToken. Auth: requires an appToken to already be configured (via ethora-configure, ETHORA_APP_TOKEN env, or ethora-app-select). Errors: returns an error if no appToken is configured. Related: use after ethora-app-select.

Switch this session's active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. Auth: the switch needs nothing, but user-auth tools only work once ethora-user-login stores a user token (login also needs a configured appJwt). Errors: none on the switch; downstream tools return 401 until login succeeds. Related: follow with ethora-user-login.

Switch this session's active auth mode to B2B, so subsequent calls authenticate as a tenant actor via the x-custom-token header. Auth: requires a b2bToken (JWT with type=server) to already be configured (via ethora-configure or ETHORA_B2B_TOKEN env). Errors: returns an error if no b2bToken is configured. Related: server-side automation — pairs with ethora-b2b-app-create, ethora-users-batch-create-v2, ethora-app-tokens-*-v2.

Set the current app context for this session so app-scoped tools can omit their appId argument. 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-use-app.

Enqueue an asynchronous broadcast job posting a message to one or more chat rooms of an app — returns a jobId; messages are not sent synchronously. Targeting is exclusive: allRooms, chatIds, or chatNames, not a mix. Requires: a selected app with at least one room (ethora-app-create-chat). Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 400 no target or conflicting targets; 404 unknown appId or room. Related: track with ethora-wait-broadcast-job-v2.

Fetch the current status and per-room results of a broadcast job by jobId (one-shot, no polling). Returns the job object with its state (pending/running/completed/failed). Requires: a selected app with at least one room (ethora-app-create-chat). Auth: app-token mode OR B2B mode with an explicit appId — must match the auth used to enqueue the job. Errors: 401/403 wrong auth; 404 unknown jobId. Related: ethora-wait-broadcast-job-v2 for a blocking wait.

Block until a broadcast job reaches a terminal state (completed or failed) or until timeoutMs — read-only polling wrapper around ethora-chats-broadcast-job-v2. Returns { done, state, job }, or { done: false, reason: "timeout" } on timeout. Requires: a jobId returned by ethora-chats-broadcast-job-v2. Auth: app-token mode OR B2B mode with an explicit appId — must match the auth used to enqueue the job. Errors: 401/403 wrong auth; 404 unknown jobId.

Upload 1–5 files to the authenticated user's Ethora file storage (POST /v2/files). Each upload is a new record (no overwrite-by-name); files passed as base64, 50MB max each. Auth: user-auth mode with an active user session (ethora-user-login first). Errors: 401 not logged in; 413 size limit exceeded; 422 unsupported mime type. Related: manage with ethora-files-get-v2 / ethora-files-delete-v2.

List the authenticated user's files, or fetch one file's metadata by id (GET /v2/files). Returns an array when id is omitted, a single record when given. Requires: a file id from ethora-files-upload-v2. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 404 unknown id or not owned by the user.

Permanently delete one of the authenticated user's files by id (DELETE /v2/files/:id). Removes the record and its stored content; not reversible. Requires: a file id from ethora-files-upload-v2. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 403 not owned by the user; 404 unknown id. Related: get ids from ethora-files-get-v2.

Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (legacy user-auth route). 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: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 413 too large; 422 unsupported document type. Related: app-token/B2B flows use ethora-sources-docs-upload-v2.

Remove a previously ingested document from an app's RAG sources by docId (legacy user-auth route). Deletes the document record and its embeddings; not reversible. Requires: a document id from ethora-sources-docs-list-v2. Auth: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown docId. Related: get docId from ethora-sources-docs-list-v2; app-token/B2B uses ethora-sources-docs-delete-v2.

Crawl a website URL and ingest its content into an app's RAG sources (app-token / B2B variant of ethora-sources-site-crawl). Async — returns once the job is accepted; followLink: true follows in-domain links and can ingest many pages. 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; 400 malformed url; 404 unknown appId. Related: ethora-sources-site-crawl-v2-wait (block until done).

Re-crawl and re-embed a previously crawled URL by its urlId, refreshing its RAG content (app-token / B2B variant of ethora-sources-site-reindex). Async — the existing source record is updated in place once indexing finishes. Requires: an indexed site URL from ethora-sources-site-list-v2 (crawled with ethora-sources-site-crawl-v2). Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId or urlId. Related: get urlId from ethora-sources-site-list-v2; ethora-sources-site-reindex-v2-wait blocks until done.

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; 400 malformed url; 504/timeout if it takes longer than timeoutMs (the job may still complete server-side — check with ethora-sources-site-list-v2).

Re-crawl and re-embed a previously crawled URL and wait for it 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. Requires: an indexed site URL from ethora-sources-site-list-v2 (crawled with ethora-sources-site-crawl-v2). Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId or urlId; 504/timeout if it takes longer than timeoutMs (the job may still complete server-side). Related: get urlId from ethora-sources-site-list-v2.

List an app's crawled website sources, including each source's id, URL, and current RAG tags. Their ids feed ethora-sources-site-tags-update-v2, ethora-sources-site-delete-url-v2-batch, and ethora-sources-site-reindex-v2. 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; empty list if nothing has been crawled.

Set the RAG retrieval tags on a crawled website source — replaces the source's tag set with the provided tags array (not additive; pass [] to clear all). Tags let the bot's ragTags narrow retrieval. Requires: an indexed site URL from ethora-sources-site-list-v2 (crawled with ethora-sources-site-crawl-v2). Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId or sourceId. Related: get sourceId from ethora-sources-site-list-v2; doc equivalent is ethora-sources-docs-tags-update-v2.

Remove a single crawled URL from an app's RAG sources, matched by its exact url string (app-token / B2B variant of ethora-sources-site-delete-url). Deletes the source record and its embeddings; not reversible. Matches on the exact stored URL string. Requires: an indexed site URL from ethora-sources-site-list-v2 (crawled with ethora-sources-site-crawl-v2). Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 url not a crawled source. Related: get the stored value from ethora-sources-site-list-v2; bulk-by-id is ethora-sources-site-delete-url-v2-batch.

Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of ethora-sources-docs-upload). 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-sources-docs-list-v2, ethora-sources-docs-delete-v2.

List an app's ingested documents, including each document's id, name, and current RAG tags. Their ids feed ethora-sources-docs-tags-update-v2 and ethora-sources-docs-delete-v2. 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; empty list if nothing has been uploaded. Related: website-sources equivalent is ethora-sources-site-list-v2.

Set the RAG retrieval tags on an ingested document — replaces the document's tag set with the provided tags array (not additive; pass [] to clear all). Tags let the bot's ragTags narrow retrieval. Requires: a document id from ethora-sources-docs-list-v2. Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId or docId. Related: get docId from ethora-sources-docs-list-v2; website-source equivalent is ethora-sources-site-tags-update-v2.

Remove a previously ingested document from an app's RAG sources by docId (app-token / B2B variant of ethora-sources-docs-delete). Deletes the document record and its embeddings; not reversible. Requires: a document id from ethora-sources-docs-list-v2. Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId or docId. Related: get docId from ethora-sources-docs-list-v2.

Provision many Ethora users (1–100) in one asynchronous batch job — the bulk equivalent of ethora-user-register. Enqueues a background job (HTTP 202); the job reports per-user conflicts rather than failing the whole batch. Returns { jobId, statusUrl }. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode; 422 usersList validation. Related: track with ethora-wait-users-batch-job-v2.

Fetch the current status and per-user results of a users batch job by jobId (one-shot, no polling). Returns the job object with its state (pending/running/completed/failed) and per-user outcomes. Requires: a jobId returned by ethora-users-batch-create-v2. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken) — must match the auth used to create the job. Errors: 401/403 not in B2B mode; 404 unknown jobId. Related: ethora-wait-users-batch-job-v2 for a blocking wait.

Block until a users batch job reaches a terminal state (completed or failed) or timeoutMs — read-only polling wrapper around ethora-users-batch-job-v2. Returns { done, state, job }, or { done: false, reason: "timeout" } on timeout. Requires: a jobId returned by ethora-users-batch-create-v2. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken) — must match the auth used to create the job. Errors: 401/403 not in B2B mode; 404 unknown jobId.

List the app tokens issued for an app — metadata only (tokenId, label, created/rotated timestamps, status); the secret token values are never returned (only shown once at create/rotate time). Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode; 400 no appId and none selected; 404 unknown appId.

Mint a new app token for an app. The secret token value is returned exactly once and cannot be retrieved again — capture it immediately. Returns the new token including its one-time secret value and tokenId. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode; 400 no appId and none selected; 404 unknown appId. Related: manage with ethora-app-tokens-list-v2 / -rotate-v2 / -revoke-v2.

Rotate an app token: revoke an existing token and issue a replacement in one step. The old tokenId is revoked immediately — anything using it stops working at once. The new secret value is returned exactly once — capture it immediately. Requires: a token id from ethora-app-tokens-list-v2. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode; 400 no appId and none selected; 404 unknown appId or tokenId. Related: ethora-app-tokens-revoke-v2 to revoke without a replacement.

Permanently revoke an app token by tokenId — it stops working immediately; any client, SDK, or MCP session still using it gets auth failures. No replacement is issued. Requires: a token id from ethora-app-tokens-list-v2. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode; 400 no appId and none selected; 404 unknown appId. Related: get tokenId from ethora-app-tokens-list-v2; ethora-app-tokens-rotate-v2 for revoke-and-replace.

One-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. Later-step failures don't undo earlier steps. Returns a per-step log including appId and the created tokens (returned once — capture them). Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: ethora-b2b-app-bootstrap-ai does sources+bot but not tokens/rooms.

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-use-user 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-users-batch-create-v2.

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.

List the current user's API keys (id, name, createdAt, expiresAt). Token values are never returned. Auth: user auth.

Revoke one of the current user's API keys by id. Clients using that key stop working immediately. Requires: a key id from ethora-api-key-list or ethora-api-key-create. Auth: user auth. Errors: 404 unknown id.

Reveal the appToken of an app the caller owns, for a chat-component snippet or a widget config. Every other tool redacts appToken, appSecret and tenantSecret from its results because tool output enters the model's context and client logs; this tool returns exactly { appId, appToken, note } and nothing else. The App Secret is never returned over MCP: it is shown only in the web dashboard (app settings, API tab), and backend integrations should use revocable server tokens from that tab instead of the secret. Requires: an app you own (ethora-app-create or ethora-app-list) and confirm: true. Auth: user auth (app owner). Errors: 401 not logged in; 403 not the owner; 404 unknown appId; validation error unless confirm is true.

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-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 { agentId, chatJid } first, otherwise POST /v2/widget/sessions returns 422 and the widget stays silent. Requires: an activated agent on the app (ethora-agents-activate-v2); 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. Related: ethora-agents-activate-v2, ethora-bot-widget-v2 (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 { 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 { 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.

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

List the default chat rooms (MUC rooms) of the currently selected Ethora app — every new user auto-joins these. Returns rooms with their JIDs and titles. Auth: user-auth mode, active session; operates against the app set via ethora-app-select. Errors: 400 no app currently selected; 401 not logged in. Related: ethora-app-get-default-rooms-with-app-id to pass appId explicitly.

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.

Permanently delete a chat room from an app the caller owns — removes the MUC room, its message archive, and all member affiliations. Irreversible; gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true. Requires: a room from ethora-app-get-default-rooms or ethora-app-create-chat. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 chatJid not a room in the app.

List the default chat rooms of a specific Ethora app, passed via appId (or the currently selected app). Returns rooms with their JIDs and titles. Requires: an appId from ethora-app-list or ethora-app-create. Auth: user-auth mode, active session; the caller needs read access (ownership or room membership). Errors: 400 no appId and none selected; 401 not logged in; 403 no read access; 404 unknown appId.

Read the authenticated user's on-chain ERC-20 wallet balance(s). Auth: user-auth (log in first). Errors: 401 not logged in; 503 wallet RPC unreachable — retry with backoff.

Create a new Ethora app (tenant) server-side using B2B auth — the partner/integrator equivalent of ethora-app-create. Allocates a fresh 24-char hex appId; does not create tokens, rooms, or a bot. Returns the new app object including appId. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken). Errors: 401/403 not in B2B mode or invalid b2bToken; 422 invalid displayName. Related: all-in-one path is ethora-b2b-app-bootstrap-ai / ethora-b2b-app-provision.

Enable the LEGACY per-app aiBot (B2B auth). NOTE: apps created via the API/B2B no longer auto-provision a legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED on a clean app. The forward path for B2B AI is the Agents API — use ethora-b2b-app-bootstrap-ai or ethora-agents-create-v2 + ethora-agent-invite-to-chat. This tool remains valid for apps that already have a legacy aiBot (e.g. admin-panel apps created with a default chat). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead.

Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead. Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId. Related: change config with ethora-bot-update-v2.

Configure the AI bot for an app — prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. Partial update — omitted fields are left unchanged. status: "on" activates the bot (best-effort; needs a prompt + LLM and a backend AI service). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead. Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId; 422 validation (e.g. an llmProvider/llmModel not enabled). Related: ethora-bot-get-v2, ethora-agents-activate-v2.

Enable the LEGACY per-app aiBot using app-token or B2B auth. NOTE: clean API/B2B-created apps have no legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED there — use the Agents API (ethora-agents-create-v2 + ethora-agent-invite-to-chat, or ethora-b2b-app-bootstrap-ai) for B2B AI. Valid for apps that already have a legacy aiBot. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead.

Turn the AI bot off for an app (sets bot status: "off") — it stops responding. The configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling restores the same behavior. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead. Auth: app-token mode OR B2B mode with an explicit appId. Errors: 401/403 wrong auth; 404 unknown appId. Related: ethora-bot-enable-v2 to turn back on.

LEGACY: read the per-app bot widget config (GET /v2/bot/widget); only apps that already have a legacy aiBot have one, API-created apps get 422. For the embeddable AI chat widget use ethora-widget-embed-snippet instead — the widget config and public widget URL metadata needed to embed the bot on a website. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead. Auth: app-token mode (after ethora-app-select + ethora-auth-use-app). Errors: 401/403 not in app-token mode or invalid appToken. Related: enable/disable via widgetPublicEnabled in ethora-bot-update-v2.

List the reusable saved agents of an app (GET /v2/apps/:appId/agents, or GET /v2/agents for the token's own app) — a saved agent is a reusable bot definition. Returns an array of agents with ids, names, and config. Auth: app-token mode (after ethora-app-select + ethora-auth-use-app). Errors: 401/403 not in app-token mode or invalid appToken; empty list if the app has no saved agents.

Fetch one reusable saved agent's full config by id (GET /v2/agents/:agentId) — prompt, LLM, RAG settings, visibility. Also sets this agent as the session's current agent context (no server-side change). Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2. Auth: app-token mode (after ethora-app-select + ethora-auth-use-app). Errors: 401/403 wrong auth; 404 agentId not an agent of the current app. Related: get ids from ethora-agents-list-v2.

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-to-chat them into the same room. See the ethora-agents-quickstart prompt for the end-to-end recipe. Requires: a selected app (ethora-app-select) or an explicit appId; the agent is owned by that app.

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-agents-list-v2 or ethora-agents-create-v2.

Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (POST /v2/agents/:agentId/clone). The source agent is unchanged; the new clone becomes the session's current agent context. Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2. Auth: app-token mode (after ethora-app-select + ethora-auth-use-app). Errors: 401/403 wrong auth; 404 source agentId not found; 422 overridden slug collides.

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-to-chat (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-agents-create-v2 -> ethora-app-create-chat -> ethora-agent-invite-to-chat); 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-embed-snippet next, ethora-bot-instances-list to inspect.

Set an Agent's visibility (private | unlisted | public). Public agents can be invited cross-app by anyone who knows the address. Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2.

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-agents-create-v2) and a room (ethora-app-create-chat) in the selected app.

Append a fragment to an Agent's SOUL.MD (its evolving identity / private notes). Operator-driven; the Agent itself can also self-edit via the same endpoint when called by ai-service. Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2.

Replace an Agent's SOUL.MD with the provided markdown. Operator-driven; alternative to -append. Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2.

List BotInstances. Filter by appId (caller's App by default) and/or agentId. Requires: at least one invited agent in the app (ethora-agent-invite-to-chat); otherwise the list is empty.

Turn a specific BotInstance on or off. Off detaches it from XMPP; on re-spawns the XMPP client live. Requires: a bot instance id from ethora-bot-instances-list (instances are created by ethora-agent-invite-to-chat).

Export an Agent as a portable bundle (GET /v2/agents/:idOrAddress/export). format=json returns the bundle object directly; feed it back to ethora-agents-import-v2 to recreate the Agent in another App/tenant. Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2.

Import an Agent from a bundle produced by ethora-agents-export-v2 (POST /v2/agents/import, application/json body IS the bundle). Optionally scope the new Agent to an owning App via ownerAppId. Requires: a bundle produced by ethora-agents-export-v2 with format json.

Diagnose a specific BotInstance for an Agent (GET /v2/agents/:idOrAddress/bot-instances/:botInstanceId/diag). Returns live XMPP/ai-service status and recent activity for troubleshooting. Requires: a bot instance id from ethora-bot-instances-list (instances are created by ethora-agent-invite-to-chat).

Send a test message from a BotInstance (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/test-message). Omit roomJid to fan out to every room the BotInstance is in. Requires the ai-service to be running. Requires: a bot instance id from ethora-bot-instances-list (instances are created by ethora-agent-invite-to-chat).

Remove a BotInstance from a chat room (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/leave-chat). The inverse of ethora-agent-invite-to-chat. Requires: a bot instance id from ethora-bot-instances-list (instances are created by ethora-agent-invite-to-chat).

Search an App's chat messages (GET /v2/apps/:appId/messages/search). B2B / tenant-actor auth. Filter by room (chatId), author (fromUserId), and time window. Requires: a selected app (ethora-app-select) or an explicit appId.

Fetch the messages surrounding a target message (GET /v2/apps/:appId/chats/:chatId/messages/context). Provide either aroundStanzaId or aroundMessageId; radius controls how many messages before/after. Requires: a message id from ethora-messages-search-v2 or ethora-chats-history-v2.

Batch per-room unread message counts for a set of users (POST /v2/apps/:appId/users/unread-counts). mode=count returns numbers (capped); mode=flag returns booleans. Requires Mongo message archiving enabled on the deployment. Requires: a selected app (ethora-app-select) or an explicit appId.

Export an App as a portable bundle (GET /v2/apps/:appId/export). format=json returns the bundle object directly. Use include to select sections (e.g. 'chats,users,sources,botInstances'). Feed the result to ethora-app-import-v2. Requires: a selected app (ethora-app-select) or an explicit appId.

Import an App from a bundle produced by ethora-app-export-v2 (POST /v2/apps/import, application/json body IS the bundle). B2B / tenant-actor auth. domainNameOverride renames the imported App's domain. Requires: a bundle produced by ethora-app-export-v2.

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-to-chat, 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-app-create-chat returns as jid) or by the bare chatId plus the selected app. Requires: a room in the selected app (ethora-app-create-chat); for replies, an agent invited into it (ethora-agent-invite-to-chat). 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-app-create-chat). 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.

One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. Source ingest and bot activation are best-effort (the app is still created if a later step fails); crawl/embedding continues asynchronously after this returns. Returns a per-step log including the new appId. Auth: B2B mode (ethora-auth-use-b2b + a configured b2bToken); internally switches to app-token mode for source-ingest steps. Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: rooms+tokens variant is ethora-b2b-app-provision.

Generate a ready-to-paste React App.tsx snippet that mounts @ethora/chat-component. Returns { filename: "App.tsx", snippet }; unpassed values are emitted as placeholders. Does not write any file. Get the appToken from ethora-app-credentials { appId, confirm: true } (other tools redact it). Auth: none required — pure code generator, no API calls. Errors: effectively none. Security note: the snippet includes appToken inline only as a quickstart convenience — do not ship hardcoded tokens to production.

Generate .env.example templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. Returns { target, template } when target is given, or { templates } with all three. Placeholder values only; does not write any file. Auth: none required — pure text generator, no API calls. Errors: effectively none.

Generate a human-readable runbook listing this server's tool calls in the right order for a B2B bootstrap, with example payloads. Documentation only — does not write any file or execute any step. Auth: none required — pure text generator, no API calls. Errors: effectively none. Related: to actually run the sequence use ethora-run-recipe or ethora-b2b-app-bootstrap-ai.

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.