Ethora MCP server
Commit Nov 13, 2026Enables AI agents to manage chat rooms, create users, deploy AI personas, and automate messaging within the Ethora platform.
Also known as dappros/ethora-mcp-cli, @ethora/mcp-server
- Stars
- 6
- Tools
- 76
- Downloads, 30 days
- 1,022
- Latest version
- 26.5.2
- Last commit
- Nov 13, 2026
- License
- MIT
What is Ethora MCP?
Ethora enables AI agents to manage chat rooms, create users, deploy AI personas, and automate messaging within the Ethora platform. It exposes 76 tools, such as ethora-configure, ethora-status, ethora-help.
Summary generated from the project's README
About Ethora MCP server
Developers can manage the Ethora messaging platform directly through AI clients like Claude, ChatGPT, and Cursor. This server allows autonomous agents to build entire chat ecosystems by creating apps, registering users, and setting up chat rooms. It provides the necessary tools to deploy AI personas and automate messaging workflows within a single interface.
Users can connect via a hosted cloud service using OAuth or personal connector URLs, which eliminates the need for local installations or manual API key pasting. For local development or private infrastructure, the server supports stdio via npx or self-hosting within an Ethora monoserver deployment. The system maintains account memory to ensure that selected apps and agents persist across different tool calls, even when using clients that start new sessions frequently.
Beyond basic messaging, the server enables advanced automation such as indexing RAG sources and generating website chat-widget embeds. It supports various authentication modes, including user, app-token, and B2B, while enforcing granular permissions through OAuth 2.1 scopes like read, write, and admin.
What you can do with it
- 1Automated user and app onboardingAn agent can register a new user account and immediately create a dedicated application for them.
- 2Managing chat room communicationsA developer can task an agent with sending messages to a specific room and waiting for a response from a bot.
- 3Setting up RAG and widgetsAgents can prepare the platform for advanced features like knowledge indexing and web embeds.
Written from the project's README. Every use case is checked against a quote from it.
How to install Ethora MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Ethora MCP in Claude Code
$ claude mcp add --env 'ETHORA_APP_JWT=<YOUR_ETHORA_APP_JWT>' --env 'ETHORA_B2B_TOKEN=<YOUR_ETHORA_B2B_TOKEN>' ethora-mcp-cli -- npx -y @ethora/mcp-serverInstall Ethora MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ethora-mcp-cli": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
],
"env": {
"ETHORA_APP_JWT": "<YOUR_ETHORA_APP_JWT>",
"ETHORA_B2B_TOKEN": "<YOUR_ETHORA_B2B_TOKEN>"
}
}
}
}Install Ethora MCP in VS Code
.vscode/mcp.json
{
"servers": {
"ethora-mcp-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
],
"env": {
"ETHORA_APP_JWT": "<YOUR_ETHORA_APP_JWT>",
"ETHORA_B2B_TOKEN": "<YOUR_ETHORA_B2B_TOKEN>"
}
}
}
}Install Ethora MCP in VS Code CLI
$ code --add-mcp '{"name":"ethora-mcp-cli","type":"stdio","command":"npx","args":["-y","@ethora/mcp-server"],"env":{"ETHORA_APP_JWT":"<YOUR_ETHORA_APP_JWT>","ETHORA_B2B_TOKEN":"<YOUR_ETHORA_B2B_TOKEN>"}}'Install Ethora MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ethora-mcp-cli": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
],
"env": {
"ETHORA_APP_JWT": "<YOUR_ETHORA_APP_JWT>",
"ETHORA_B2B_TOKEN": "<YOUR_ETHORA_B2B_TOKEN>"
}
}
}
}Install Ethora MCP in Codex
$ codex mcp add ethora-mcp-cli --env 'ETHORA_APP_JWT=<YOUR_ETHORA_APP_JWT>' --env 'ETHORA_B2B_TOKEN=<YOUR_ETHORA_B2B_TOKEN>' -- npx -y @ethora/mcp-serverInstall Ethora MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.ethora-mcp-cli] command = "npx" args = ["-y", "@ethora/mcp-server"] [mcp_servers.ethora-mcp-cli.env] ETHORA_APP_JWT = "<YOUR_ETHORA_APP_JWT>" ETHORA_B2B_TOKEN = "<YOUR_ETHORA_B2B_TOKEN>"
Install Ethora MCP in Gemini CLI
$ gemini mcp add -s user -e 'ETHORA_APP_JWT=<YOUR_ETHORA_APP_JWT>' -e 'ETHORA_B2B_TOKEN=<YOUR_ETHORA_B2B_TOKEN>' ethora-mcp-cli npx -- -y @ethora/mcp-serverInstall Ethora MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ethora-mcp-cli": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
],
"env": {
"ETHORA_APP_JWT": "<YOUR_ETHORA_APP_JWT>",
"ETHORA_B2B_TOKEN": "<YOUR_ETHORA_B2B_TOKEN>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @ethora/mcp-server 26.5.2 in an isolated container with no network and no keys. It answered and listed 76 tools.
Ethora MCP tools 76
Read from the server with tools/listethora-configureSet the Ethora API URL and credentials for this MCP session. Auth: none required — this is the tool that establishes auth material. Side effects: stores values **in memory only**, scoped to this MCP process; nothing is written to disk and the values reset when the server restarts. Each call merges — fields you omit keep their previous value. An alternative to setting the same values via env vars (ETHORA_API_URL / ETHORA_APP_JWT / ETHORA_APP_TOKEN / ETHORA_B2B_TOKEN). Idempotent: yes. Failure modes: rarely fails; returns an error only if a value is structurally invalid. Returns: the resulting (redacted) client state. Follow with `ethora-status` to confirm, `ethora-doctor` to test connectivity, then an `ethora-auth-use-*` tool to pick the active mode.
ethora-statusReport the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present, and the currently selected appId/agentId. Auth: none required. Side effects: none — read-only. Idempotent: yes. Failure modes: effectively none. Returns: a state object with booleans like `hasAppJwt` / `hasB2BToken` / `hasUserToken` (credential *values* are never echoed back). Use it to decide which `ethora-auth-use-*` tool to call next, or run `ethora-doctor` for an active connectivity check.
ethora-helpTask-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends the next tool calls + one-click recipes based on the current session state. Auth: none required — inspects state, makes no API calls. Side effects: none — read-only. Idempotent: yes; recommendations change only as the session state changes. Failure modes: effectively none. When to use: call this first if you're unsure which auth mode or tool sequence fits your goal. To then run a recommended sequence, pass its recipe id to `ethora-run-recipe`.
ethora-run-recipeExecute 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, etc.). Auth: depends on the recipe's steps; each step uses whatever auth mode/credentials it needs, so configure those first (see `ethora-help` for the right recipe + prerequisites). Side effects: runs entirely in-process — **no shell, no file writes**. Real side effects come only from the underlying tool steps (which may create apps, send messages, etc.). Use `dryRun: true` to preview the resolved steps without executing any of them. Idempotent: only as idempotent as the steps it runs — a recipe that calls `ethora-app-create` is not idempotent. Failure modes: stops at the first failing step and returns what completed plus the error; a missing required `vars` entry fails fast before any step runs. Returns: per-step results. Omit `recipeId` to list the runnable recipes for the given `goal` (or `goal: "auto"`).
ethora-doctorDiagnose the session: validate that the config is internally consistent for the active auth mode and actively ping the Ethora API. Auth: none required, but the report is tailored to whatever auth mode/credentials are currently set. Side effects: makes one real network call — `GET /v1/ping` against the configured API URL. No state is changed. Idempotent: yes. Failure modes: the tool itself rarely throws; instead it returns `suggestions` for misconfigurations and a `ping.ok: false` block (with the error) when the API is unreachable. Returns: `{ state, checks, ping, suggestions }`. Run this after `ethora-configure` to confirm everything is wired up before attempting real operations.
ethora-auth-use-appSwitch 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`, the ETHORA_APP_TOKEN env var, or `ethora-app-select` with an `appToken`). Side effects: changes session state only (the active auth mode); no API call, no server-side change. Idempotent: yes. Failure modes: returns an error if no `appToken` is configured — set one first. When to use: after `ethora-app-select` when you want app-scoped convenience routes (`/v2/...` resolved against the selected app). For explicit tenant-actor routes use `ethora-auth-use-b2b` instead.
ethora-auth-use-userSwitch this session's active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. Auth: switching the mode itself needs nothing, but user-auth tools only work once `ethora-user-login` has stored a user token. Login also requires a configured `appJwt`. Side effects: changes session state only; no API call, no server-side change. Idempotent: yes. Failure modes: none on the switch itself; downstream user-auth tools return 401 until `ethora-user-login` succeeds. When to use: first-time local/manual use — switch to this mode, then call `ethora-user-login`. For repeatable automation prefer `ethora-auth-use-b2b`.
ethora-auth-use-b2bSwitch 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` to already be configured (via `ethora-configure` or the ETHORA_B2B_TOKEN env var) — a JWT with `type=server`. Side effects: changes session state only; no API call, no server-side change. Idempotent: yes. Failure modes: returns an error if no `b2bToken` is configured — set one first. When to use: server-side automation and partner provisioning. B2B tools take an explicit `appId` (or use the one from `ethora-app-select`). Pairs with `ethora-b2b-app-create`, `ethora-b2b-app-bootstrap-ai`, `ethora-users-batch-create-v2`, and the `ethora-app-tokens-*-v2` tools.
ethora-app-selectSet the current app context for this session so app-scoped tools can omit their `appId` argument. Auth: none required to set the context; the tools you then call still need their own auth mode. Side effects: session state only — stores `currentAppId` and, if given, `appToken`. If `appToken` is supplied the active auth mode defaults to app-token unless `authMode` overrides it. No API call, no server-side change. Idempotent: yes — calling again just overwrites the selection. Failure modes: effectively none; passing an `appId` that doesn't exist is not validated here — the first app-scoped API call will surface the 404. When to use: once per app you're working with, before broadcast/sources/bot/agents tools. Pairs with `ethora-auth-use-app`.
ethora-chats-broadcast-v2Enqueue an asynchronous broadcast job that posts a message to one or more chat rooms of an app. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: creates a background job on the server and returns immediately with a `jobId` — the messages are **not** sent synchronously. Targeting is exclusive: pass `allRooms: true`, or a `chatIds` list, or a `chatNames` list — not a mix. Idempotent: no — each call enqueues a new job; calling twice broadcasts twice. Failure modes: 401/403 on missing/wrong auth; 400 if no target is specified or targets conflict; 404 if `appId` or a target room doesn't exist. Returns: `{ jobId, ... }`. Track it with `ethora-chats-broadcast-job-v2` (one-shot status) or `ethora-wait-broadcast-job-v2` (poll to completion).
ethora-chats-broadcast-job-v2Fetch the current status and results of a broadcast job by `jobId` (one-shot, no polling). Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if the `jobId` is unknown for this app. Returns: the job object including its `state` (`pending` / `running` / `completed` / `failed`) and per-room results. For a blocking wait-until-done, use `ethora-wait-broadcast-job-v2` instead of polling this yourself.
ethora-wait-broadcast-job-v2Block until a broadcast job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-chats-broadcast-job-v2` calls. Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when the job finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-chats-broadcast-job-v2`).
| ethora-configure | Set the Ethora API URL and credentials for this MCP session. Auth: none required — this is the tool that establishes auth material. Side effects: stores values **in memory only**, scoped to this MCP process; nothing is written to disk and the values reset when the server restarts. Each call merges — fields you omit keep their previous value. An alternative to setting the same values via env vars (ETHORA_API_URL / ETHORA_APP_JWT / ETHORA_APP_TOKEN / ETHORA_B2B_TOKEN). Idempotent: yes. Failure modes: rarely fails; returns an error only if a value is structurally invalid. Returns: the resulting (redacted) client state. Follow with `ethora-status` to confirm, `ethora-doctor` to test connectivity, then an `ethora-auth-use-*` tool to pick the active mode. | |
| ethora-status | Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present, and the currently selected appId/agentId. Auth: none required. Side effects: none — read-only. Idempotent: yes. Failure modes: effectively none. Returns: a state object with booleans like `hasAppJwt` / `hasB2BToken` / `hasUserToken` (credential *values* are never echoed back). Use it to decide which `ethora-auth-use-*` tool to call next, or run `ethora-doctor` for an active connectivity check. | |
| ethora-help | Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends the next tool calls + one-click recipes based on the current session state. Auth: none required — inspects state, makes no API calls. Side effects: none — read-only. Idempotent: yes; recommendations change only as the session state changes. Failure modes: effectively none. When to use: call this first if you're unsure which auth mode or tool sequence fits your goal. To then run a recommended sequence, pass its recipe id to `ethora-run-recipe`. | |
| 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, etc.). Auth: depends on the recipe's steps; each step uses whatever auth mode/credentials it needs, so configure those first (see `ethora-help` for the right recipe + prerequisites). Side effects: runs entirely in-process — **no shell, no file writes**. Real side effects come only from the underlying tool steps (which may create apps, send messages, etc.). Use `dryRun: true` to preview the resolved steps without executing any of them. Idempotent: only as idempotent as the steps it runs — a recipe that calls `ethora-app-create` is not idempotent. Failure modes: stops at the first failing step and returns what completed plus the error; a missing required `vars` entry fails fast before any step runs. Returns: per-step results. Omit `recipeId` to list the runnable recipes for the given `goal` (or `goal: "auto"`). | |
| ethora-doctor | Diagnose the session: validate that the config is internally consistent for the active auth mode and actively ping the Ethora API. Auth: none required, but the report is tailored to whatever auth mode/credentials are currently set. Side effects: makes one real network call — `GET /v1/ping` against the configured API URL. No state is changed. Idempotent: yes. Failure modes: the tool itself rarely throws; instead it returns `suggestions` for misconfigurations and a `ping.ok: false` block (with the error) when the API is unreachable. Returns: `{ state, checks, ping, suggestions }`. Run this after `ethora-configure` to confirm everything is wired up before attempting real operations. | |
| ethora-auth-use-app | 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`, the ETHORA_APP_TOKEN env var, or `ethora-app-select` with an `appToken`). Side effects: changes session state only (the active auth mode); no API call, no server-side change. Idempotent: yes. Failure modes: returns an error if no `appToken` is configured — set one first. When to use: after `ethora-app-select` when you want app-scoped convenience routes (`/v2/...` resolved against the selected app). For explicit tenant-actor routes use `ethora-auth-use-b2b` instead. | |
| ethora-auth-use-user | Switch this session's active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. Auth: switching the mode itself needs nothing, but user-auth tools only work once `ethora-user-login` has stored a user token. Login also requires a configured `appJwt`. Side effects: changes session state only; no API call, no server-side change. Idempotent: yes. Failure modes: none on the switch itself; downstream user-auth tools return 401 until `ethora-user-login` succeeds. When to use: first-time local/manual use — switch to this mode, then call `ethora-user-login`. For repeatable automation prefer `ethora-auth-use-b2b`. | |
| ethora-auth-use-b2b | 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` to already be configured (via `ethora-configure` or the ETHORA_B2B_TOKEN env var) — a JWT with `type=server`. Side effects: changes session state only; no API call, no server-side change. Idempotent: yes. Failure modes: returns an error if no `b2bToken` is configured — set one first. When to use: server-side automation and partner provisioning. B2B tools take an explicit `appId` (or use the one from `ethora-app-select`). Pairs with `ethora-b2b-app-create`, `ethora-b2b-app-bootstrap-ai`, `ethora-users-batch-create-v2`, and the `ethora-app-tokens-*-v2` tools. | |
| ethora-app-select | Set the current app context for this session so app-scoped tools can omit their `appId` argument. Auth: none required to set the context; the tools you then call still need their own auth mode. Side effects: session state only — stores `currentAppId` and, if given, `appToken`. If `appToken` is supplied the active auth mode defaults to app-token unless `authMode` overrides it. No API call, no server-side change. Idempotent: yes — calling again just overwrites the selection. Failure modes: effectively none; passing an `appId` that doesn't exist is not validated here — the first app-scoped API call will surface the 404. When to use: once per app you're working with, before broadcast/sources/bot/agents tools. Pairs with `ethora-auth-use-app`. | |
| ethora-chats-broadcast-v2 | Enqueue an asynchronous broadcast job that posts a message to one or more chat rooms of an app. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: creates a background job on the server and returns immediately with a `jobId` — the messages are **not** sent synchronously. Targeting is exclusive: pass `allRooms: true`, or a `chatIds` list, or a `chatNames` list — not a mix. Idempotent: no — each call enqueues a new job; calling twice broadcasts twice. Failure modes: 401/403 on missing/wrong auth; 400 if no target is specified or targets conflict; 404 if `appId` or a target room doesn't exist. Returns: `{ jobId, ... }`. Track it with `ethora-chats-broadcast-job-v2` (one-shot status) or `ethora-wait-broadcast-job-v2` (poll to completion). | |
| ethora-chats-broadcast-job-v2 | Fetch the current status and results of a broadcast job by `jobId` (one-shot, no polling). Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if the `jobId` is unknown for this app. Returns: the job object including its `state` (`pending` / `running` / `completed` / `failed`) and per-room results. For a blocking wait-until-done, use `ethora-wait-broadcast-job-v2` instead of polling this yourself. | |
| ethora-wait-broadcast-job-v2 | Block until a broadcast job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-chats-broadcast-job-v2` calls. Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when the job finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-chats-broadcast-job-v2`). |
Show all 76 toolsShow fewer tools
ethora-files-upload-v2Upload one or more files to the authenticated user's Ethora file storage (`POST /v2/files`). Auth: user-auth mode with an active user session (`ethora-user-login` first). Side effects: creates file records server-side owned by the logged-in user; each upload is a new record (no overwrite-by-name). Idempotent: no — re-uploading creates duplicate records. Input design: files are passed as base64 so the MCP server never touches your local filesystem. Client-side guardrail rejects any single file over 50MB before upload; the Ethora server enforces its own limits too. Failure modes: 401 if not logged in; 413 if the server's size limit is exceeded; 422 on an unsupported mime type. Per-call limit: 1–5 files. Returns: the created file records (with ids). Manage them with `ethora-files-get-v2` and `ethora-files-delete-v2`.
ethora-files-get-v2List the authenticated user's files, or fetch one file's metadata by id (`GET /v2/files`). Auth: user-auth mode with an active user session. Side effects: none — read-only. Idempotent: yes. Failure modes: 401 if not logged in; 404 if a specific `id` is given but not found / not owned by the user. Returns: an array of file records when `id` is omitted, or a single record when `id` is given. Use the ids with `ethora-files-delete-v2`.
ethora-files-delete-v2Permanently delete one of the authenticated user's files by id (`DELETE /v2/files/:id`). Auth: user-auth mode with an active user session. Side effects: removes the file record and its stored content. Not reversible. Idempotent: yes after success — a second call returns 404. Failure modes: 401 if not logged in; 403 if the file is not owned by the user; 404 if the `id` does not exist. Get ids from `ethora-files-get-v2`.
ethora-sources-site-crawlCrawl a website URL and ingest its content into an app's RAG sources, so the app's AI bot can answer from it (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a crawl + embedding job on the server; pages become queryable RAG context once indexing finishes (not synchronous). With `followLink: true` the crawler also follows in-domain links, which can ingest many pages. Idempotent: no — re-crawling the same URL adds/updates source records; combined with `followLink` it can fan out broadly. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-reindex` (refresh), `ethora-sources-site-delete-url` (remove), `ethora-sources-docs-upload` (ingest documents instead of a URL). For app-token / B2B flows use `ethora-sources-site-crawl-v2`.
ethora-sources-site-reindexRe-crawl and re-embed a previously crawled URL by its `urlId`, refreshing the RAG content for that page (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a refresh job on the server; the page's existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes the same record again. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` or `urlId` is unknown. When to use: the source page changed and you want the bot to pick up the new content. Get `urlId` values from `ethora-sources-site-list-v2`. For app-token / B2B flows use `ethora-sources-site-reindex-v2`.
ethora-sources-site-delete-urlRemove a single crawled URL from an app's RAG sources, matched by its exact url string (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes the source record and its embeddings; the app's bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if the exact `url` string isn't a crawled source. Note: matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several at once use `ethora-sources-site-delete-records-v1`.
ethora-sources-site-delete-records-v1Bulk-remove crawled URLs from an app's RAG sources in one call, matched by exact url strings (legacy owner/admin user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes each matching source record and its embeddings. Not reversible. Idempotent: yes — URLs not present are skipped. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` is invalid. Per-call limit: 1–100 URLs. When to use: cleaning up many pages at once. For the single-URL variant use `ethora-sources-site-delete-url`; for app-token / B2B flows use `ethora-sources-site-delete-url-v2-batch`.
ethora-sources-docs-uploadUpload documents (PDF, text, etc.) into an app's RAG sources so the app's AI bot can answer from them (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-delete` (remove), `ethora-sources-site-crawl` (ingest a URL instead). For app-token / B2B flows use `ethora-sources-docs-upload-v2`.
ethora-sources-docs-deleteRemove a previously ingested document from an app's RAG sources by `docId` (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes the document record and its embeddings; the app's bot can no longer answer from it. Not reversible (re-add via `ethora-sources-docs-upload`). Idempotent: yes after success — a second call returns 404. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`. For app-token / B2B flows use `ethora-sources-docs-delete-v2`.
ethora-sources-site-crawl-v2Crawl a website URL and ingest its content into an app's RAG sources (app-token / B2B variant of `ethora-sources-site-crawl`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a crawl + embedding job; pages become queryable RAG context once indexing finishes (not synchronous — this returns once the job is accepted). With `followLink: true` the crawler also follows in-domain links and can ingest many pages. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-crawl-v2-wait` (block until done), `ethora-sources-site-list-v2` (see results), `ethora-sources-site-reindex-v2` (refresh), `ethora-sources-site-delete-url-v2` (remove).
ethora-sources-site-reindex-v2Re-crawl and re-embed a previously crawled URL by its `urlId`, refreshing its RAG content (app-token / B2B variant of `ethora-sources-site-reindex`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a refresh job; the existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes again. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown. Get `urlId` values from `ethora-sources-site-list-v2`. Use `ethora-sources-site-reindex-v2-wait` to block until done.
ethora-sources-site-crawl-v2-waitCrawl a website URL and block until the server finishes the request — a single-call, long-timeout variant of `ethora-sources-site-crawl-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-crawl-v2` (crawl + embed into RAG sources), but this MCP call blocks for up to `timeoutMs` waiting for the server's response instead of returning as soon as the job is accepted. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 504/timeout if the crawl takes longer than `timeoutMs` (the job may still complete server-side — check with `ethora-sources-site-list-v2`). Returns: `{ done: true, durationMs, result }`. Use the non-wait `ethora-sources-site-crawl-v2` if you'd rather not block.
ethora-sources-site-reindex-v2-waitRe-crawl and re-embed a previously crawled URL and block until the server finishes — a single-call, long-timeout variant of `ethora-sources-site-reindex-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-reindex-v2` (refresh the source record's RAG content), but this MCP call blocks for up to `timeoutMs`. Idempotent: effectively yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side). Returns: `{ done: true, durationMs, result }`. Get `urlId` values from `ethora-sources-site-list-v2`.
ethora-sources-site-list-v2List an app's crawled website sources, including each source's id, URL, and current RAG tags. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; returns an empty list if nothing has been crawled. Returns: site source records. Their ids feed `ethora-sources-site-tags-update-v2`, `ethora-sources-site-delete-url-v2-batch`, and `ethora-sources-site-reindex-v2` (`urlId`).
ethora-sources-site-tags-update-v2Set the RAG retrieval tags on a crawled website source. Tags let the bot's `ragTags` setting narrow which sources it retrieves from. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **replaces** the source's tag set with the provided `tags` array (it is not additive — pass the full desired set, or an empty array to clear all tags). Idempotent: yes — re-sending the same tags is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `sourceId` is unknown. Get `sourceId` values from `ethora-sources-site-list-v2`. The doc equivalent is `ethora-sources-docs-tags-update-v2`.
ethora-sources-site-delete-url-v2Remove 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`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deletes the source record and its embeddings; the bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl-v2`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401/403 on missing/wrong auth; 404 if the exact `url` isn't a crawled source. Matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several by id use `ethora-sources-site-delete-url-v2-batch`.
ethora-sources-docs-upload-v2Upload documents (PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-sources-docs-upload`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-list-v2` (see results), `ethora-sources-docs-delete-v2` (remove), `ethora-sources-docs-tags-update-v2` (tag).
ethora-sources-docs-list-v2List an app's ingested documents, including each document's id, name, and current RAG tags. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; returns an empty list if nothing has been uploaded. Returns: document records. Their ids feed `ethora-sources-docs-tags-update-v2` and `ethora-sources-docs-delete-v2`. The website-sources equivalent is `ethora-sources-site-list-v2`.
ethora-sources-docs-tags-update-v2Set the RAG retrieval tags on an ingested document. Tags let the bot's `ragTags` setting narrow which sources it retrieves from. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **replaces** the document's tag set with the provided `tags` array (it is not additive — pass the full desired set, or an empty array to clear all tags). Idempotent: yes — re-sending the same tags is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`. The website-source equivalent is `ethora-sources-site-tags-update-v2`.
ethora-sources-docs-delete-v2Remove a previously ingested document from an app's RAG sources by `docId` (app-token / B2B variant of `ethora-sources-docs-delete`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deletes the document record and its embeddings; the bot can no longer answer from it. Not reversible (re-add via `ethora-sources-docs-upload-v2`). Idempotent: yes after success — a second call returns 404. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`.
ethora-users-batch-create-v2Provision many Ethora users in one asynchronous batch job — the bulk equivalent of `ethora-user-register`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: enqueues a background job (server responds HTTP 202) — users are **not** created synchronously. Each user is created under the B2B tenant's app. With `bypassEmailConfirmation: true` users are usable immediately; otherwise each receives a verification email. Idempotent: no — re-running re-attempts creation; the job itself reports per-user conflicts (already-registered emails) rather than failing the whole batch. Failure modes: 401/403 if not in B2B mode; 422 if the `usersList` fails validation. Per-call limit: 1–100 users. Returns: `{ jobId, statusUrl }`. Track it with `ethora-users-batch-job-v2` (one-shot) or `ethora-wait-users-batch-job-v2` (poll to completion).
ethora-users-batch-job-v2Fetch the current status and per-user results of a users batch job by `jobId` (one-shot, no polling). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: the job object including its `state` (`pending` / `running` / `completed` / `failed`) and per-user outcomes (created / conflict / error). For a blocking wait-until-done, use `ethora-wait-users-batch-job-v2`.
ethora-wait-users-batch-job-v2Block until a users batch job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-users-batch-job-v2` calls. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-users-batch-job-v2`).
ethora-app-tokens-list-v2List the app tokens issued for an app — **metadata only**, the secret token values are never returned. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 400 if no `appId` is given and none is selected; 404 if `appId` is invalid. Returns: token records with `tokenId`, label, created/rotated timestamps, and status. The actual token strings are only ever shown once, at create/rotate time (`ethora-app-tokens-create-v2`, `ethora-app-tokens-rotate-v2`).
ethora-app-tokens-create-v2Mint a new app token for an app. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: creates a new app token server-side. **The secret token value is returned exactly once in this response and cannot be retrieved again** — capture it immediately (e.g. store it, or pass it to `ethora-app-select`). Idempotent: no — each call mints a distinct token. Failure modes: 401/403 if not in B2B mode; 400 if no `appId` is given and none is selected; 404 if `appId` is invalid. Returns: the new token including its one-time secret value and its `tokenId`. Manage it later with `ethora-app-tokens-list-v2`, `ethora-app-tokens-rotate-v2`, `ethora-app-tokens-revoke-v2`.
ethora-app-tokens-rotate-v2Rotate an app token: revoke an existing token and issue a replacement in one step. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: the old `tokenId` is revoked **immediately** — anything still using it stops working at once — and a new token is created. **The new secret value is returned exactly once** — capture it immediately. Idempotent: no — each call revokes and re-issues. Failure modes: 401/403 if not in B2B mode; 404 if `appId` or `tokenId` is unknown; 400 if no `appId` is given and none is selected. Returns: the new token including its one-time secret value and `tokenId`. Use `ethora-app-tokens-revoke-v2` if you only want to revoke without a replacement.
ethora-app-tokens-revoke-v2Permanently revoke an app token by `tokenId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: the token stops working **immediately** — any client, SDK, or MCP session still using it will start getting auth failures. No replacement is issued (use `ethora-app-tokens-rotate-v2` for revoke-and-replace). Idempotent: yes — revoking an already-revoked token succeeds as a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is unknown; 400 if no `appId` is given and none is selected. Get `tokenId` values from `ethora-app-tokens-list-v2`.
ethora-b2b-app-provisionOne-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Internally uses the first minted app token for the bot/room steps. Side effects: runs several real operations in sequence — `appCreate` (B2B), `app-tokens-create` (×N), room creation (×N), bot configure/enable. Returns a per-step log; later-step failures don't undo earlier steps (the app and any tokens already exist). Idempotent: no — each call creates a new app, new tokens, and new rooms. Failure modes: aborts with the partial step log if app creation fails; the previous auth mode is restored best-effort on error. Returns: a per-step result log including `appId` and the created tokens (tokens are returned **once** — capture them). Sibling orchestrator `ethora-b2b-app-bootstrap-ai` does sources+bot but not tokens/rooms.
ethora-user-loginAuthenticate as an existing Ethora user with email + password. Auth: user-auth mode (call `ethora-auth-use-user` first) and a configured `appJwt` (env or `ethora-configure`). Side effects: stores the resulting user session token in this MCP session; unlocks user-auth tools (`ethora-app-list`, `ethora-app-create`, `ethora-files-*`, `ethora-wallet-*`). Idempotent: yes — safe to retry on transport failures. Failure modes: 401/403 on bad credentials; 404 if the email isn't registered; 429 if the Ethora server's per-IP login rate limit is hit (retry with backoff). Related: `ethora-user-register` (create account first), `ethora-auth-use-user` (switch mode), `ethora-status` (verify session).
ethora-user-registerRegister a new Ethora end-user account by email + first/last name. Auth: user-auth mode and a configured `appJwt` (env or `ethora-configure`) — the JWT tells the server which app the new user belongs to. Side effects: creates a pending user record on the Ethora server and triggers a verification email to the address; the user must click the link in that email before `ethora-user-login` will succeed. Idempotent: safe to retry on transport failures (server deduplicates by email within an app). Calling twice with a fresh email creates one account; calling with an already-registered email returns 422. Failure modes: 422 with a validation error if the email is already registered, if names violate server rules, or if the configured `appJwt` is invalid; 401 if no `appJwt` is configured. When to use: end-user self-serve sign-up flows. For bulk B2B user provisioning prefer `ethora-users-batch-create-v2`.
ethora-app-listList all Ethora apps (tenants) owned by the currently logged-in user. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: none — read-only. Idempotent: yes — repeated calls return the same set unless an app is created/deleted in between. Failure modes: 401 if not logged in; returns an empty list if the user owns no apps. Returns: an array where each entry includes `appId` (24-char hex ObjectId), `displayName`, `domainName`, ownership and bot-status metadata. Pass `appId` into `ethora-app-update`, `ethora-app-delete`, or `ethora-app-select` for app-scoped flows.
ethora-app-createCreate a new Ethora app (tenant) owned by the currently logged-in user. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: provisions a new app record on the server, allocates a fresh 24-char hex `appId`, sets the caller as owner. Each app counts against the owner's plan limit. Idempotent: no — calling twice creates two apps. Use `ethora-app-list` first if you want to reuse an existing app. Failure modes: 401 if not logged in; 402/403 if the owner's plan limit is reached; 422 if `displayName` violates server rules. Returns: the new app object including `appId`. Pass it to `ethora-app-update` (set domainName/colors/bot), `ethora-app-select` (switch into app-token flows), or `ethora-app-delete` (remove). When to use: interactive setup by a logged-in user. For server-to-server provisioning prefer `ethora-b2b-app-create` or the one-call orchestrator `ethora-b2b-app-bootstrap-ai`.
ethora-app-updateUpdate mutable fields on an existing Ethora app the caller owns (displayName, domainName, appDescription, primaryColor, botStatus). Auth: user-auth mode and an active user session; the caller must own the app. Side effects: **partial update** — only the fields you pass are changed; omitted fields keep their previous values. `domainName` changes affect the public URL (`<domain>.ethora.com`) immediately. `botStatus: "on"` enables the bot only if the app has a configured prompt (use `ethora-bot-update-v2` / `ethora-bot-enable-v2` for the AI bot lifecycle). Idempotent: yes — repeating an update with the same values is a no-op. Failure modes: 401 if not logged in; 403 if not the owner; 404 if `appId` is invalid; 422 on field validation failure (e.g. `domainName` already taken, `primaryColor` not in `#RRGGBB` format). When to use: change branding, route the web app under a custom subdomain, or quickly toggle the bot on/off without re-running setup.
ethora-app-get-default-roomsList the default chat rooms (MUC rooms) of the currently selected Ethora app — every new user of the app auto-joins these. Auth: user-auth mode and an active user session. Operates against the currently selected app — call `ethora-app-select` first, or use `ethora-app-get-default-rooms-with-app-id` to pass `appId` explicitly. Side effects: none — read-only. Idempotent: yes. Failure modes: 400 if no app is currently selected in this MCP session; 401 if not logged in. Returns: array of rooms with their JIDs and titles. Use the JIDs with `ethora-chats-broadcast-v2`, `ethora-app-create-chat` (add more), or `ethora-app-delete-chat` (remove).
ethora-app-create-chatCreate a new chat room (MUC room) inside an Ethora app the caller owns. Auth: user-auth mode and an active user session; the caller must own the app. Side effects: provisions a new MUC room with the given `title`. If `pinned: true` the room is added to the app's default rooms list — every new user of the app will auto-join it from that point on. Existing users are **not** auto-added; for that, see the chat membership v2 endpoints. Idempotent: no — calling twice with the same title creates two distinct rooms with different JIDs. Failure modes: 401 if not logged in; 403 if the caller does not own the app; 404 if `appId` is invalid; 422 if `title` is empty or violates server rules. Returns: the new room object including its JID. Use the JID with `ethora-chats-broadcast-v2` to send messages or `ethora-app-delete-chat` to remove.
ethora-app-delete-chatPermanently delete a chat room from an Ethora app the caller owns. **Destructive and irreversible.** Gated behind `ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true`; the tool refuses to register otherwise. Auth: user-auth mode and an active user session; the caller must own the app. Side effects: removes the MUC room, its message archive, and all member affiliations. Participants will see "room destroyed" on their next reconnect. Idempotent: yes after success — subsequent calls return 404. Failure modes: 401 if not logged in; 403 if not the owner; 404 if `chatJid` is not a room in the app. When to use: explicit room tear-down. To remove only from the default rooms list (without destroying the room) update the default-rooms config rather than deleting.
ethora-app-get-default-rooms-with-app-idList the default chat rooms of a specific Ethora app, passed via `appId` (or defaulted to the currently selected app). Auth: user-auth mode and an active user session. The caller must have read access to the app — either ownership, or membership of at least one of its rooms. Side effects: none — read-only. Idempotent: yes. Failure modes: 400 if neither `appId` is passed nor an app is currently selected; 401 if not logged in; 403 if the caller lacks read access; 404 if `appId` does not exist. Returns: array of rooms with their JIDs and titles. Use `ethora-app-get-default-rooms` for the simpler "current app only" variant.
ethora-wallet-get-balanceRead the on-chain wallet balance for the currently authenticated user, across the ERC-20 token(s) the Ethora backend tracks for them. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: none — read-only, no gas consumed. Idempotent: yes — safe to call repeatedly. Failure modes: 401 if not logged in; 503 if the wallet RPC is temporarily unreachable (safe to retry on 503 with backoff). Returns: balances in the units the Ethora backend reports (typically whole-token integers — confirm with your deployment). Pair with `ethora-wallet-erc20-transfer` to spend.
ethora-b2b-app-createCreate a new Ethora app (tenant) server-side using B2B auth — the partner/integrator equivalent of `ethora-app-create`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: provisions a new app record owned by the B2B tenant and allocates a fresh 24-char hex `appId`. Does not create tokens, rooms, or a bot. Idempotent: no — calling twice creates two apps. Failure modes: 401/403 if not in B2B mode or the `b2bToken` is invalid; 422 if `displayName` violates server rules. Returns: the new app object including `appId`. Next steps: `ethora-app-tokens-create-v2` (mint an appToken), `ethora-app-select` (set context), `ethora-bot-update-v2` (configure the bot). For the all-in-one path use `ethora-b2b-app-bootstrap-ai` or `ethora-b2b-app-provision`.
ethora-b2b-bot-enableTurn on the AI bot for an app via B2B auth (sets `botStatus: "on"` on the app record). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: flips the app's bot status to on; the backend then makes a **best-effort** activation against the configured AI service. The bot only actually responds if the app already has a prompt + LLM configured (see `ethora-bot-update-v2`) and the Ethora backend has AI service URL/secret set. Idempotent: yes — enabling an already-enabled bot is a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is invalid; 400 if no `appId` is given and none is selected. Note: this is a thin convenience over `ethora-app-update`. For full bot configuration (prompt, LLM, RAG, greeting) use `ethora-bot-update-v2`; `ethora-bot-enable-v2` is the app-token-friendly equivalent.
ethora-bot-get-v2Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Returns: the bot settings object. Use it to inspect before changing things with `ethora-bot-update-v2`, or to confirm an `ethora-agents-activate-v2` took effect.
ethora-bot-update-v2Configure the AI bot for an app — its prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **partial update** — only the fields you pass are changed; omitted fields keep their values. Setting `status: "on"` activates the bot (best-effort against the configured AI service — needs a prompt + LLM and a backend AI service configured). Idempotent: yes — re-sending the same values is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; 422 on field validation failure (e.g. an `llmProvider`/`llmModel` your backend doesn't have enabled). Related: `ethora-bot-get-v2` (inspect first), `ethora-bot-enable-v2` / `ethora-bot-disable-v2` (just toggle status), `ethora-agents-activate-v2` (apply a saved agent's config instead of setting fields by hand).
ethora-bot-enable-v2Turn the AI bot on for an app (sets bot `status: "on"`), optionally setting its trigger at the same time. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: activates the bot. It only actually responds if a prompt + LLM are configured (see `ethora-bot-update-v2` or `ethora-agents-activate-v2`) and the Ethora backend has an AI service configured. Idempotent: yes — enabling an already-on bot is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Thin convenience over `ethora-bot-update-v2` for the common "just turn it on" case. Pair with `ethora-bot-disable-v2` to turn it off.
ethora-bot-disable-v2Turn the AI bot off for an app (sets bot `status: "off"`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deactivates the bot — it stops responding to messages. The bot's configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling later restores the same behavior. Idempotent: yes — disabling an already-off bot is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Thin convenience over `ethora-bot-update-v2`. Pair with `ethora-bot-enable-v2` to turn it back on.
ethora-bot-widget-v2Read the public chat-widget / embed configuration for the current app's bot (`GET /v2/bot/widget`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in app-token mode or the appToken is invalid. Returns: the widget config and the public widget URL metadata — what you need to embed the bot on a website. To enable/disable the public widget, set `widgetPublicEnabled` via `ethora-bot-update-v2`.
ethora-agents-list-v2List the reusable saved agents owned by the current app (`GET /v2/agents`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in app-token mode or the appToken is invalid; returns an empty list if the app has no saved agents. Returns: an array of agents with their ids, names, and config. A saved agent is a reusable bot definition — use the ids with `ethora-agents-get-v2`, `ethora-agents-update-v2`, `ethora-agents-clone-v2`, or `ethora-agents-activate-v2`.
ethora-agents-get-v2Fetch one reusable saved agent's full config by id (`GET /v2/agents/:agentId`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: also sets this agent as the current agent context for the session (so later agent tools can omit `agentId`). No server-side change. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app. Returns: the agent object (prompt, LLM, RAG settings, visibility, etc.). Get ids from `ethora-agents-list-v2`.
ethora-agents-create-v2Create a new reusable saved agent — a named, reusable bot definition (prompt + LLM + RAG settings + identity) that can later be activated onto any app (`POST /v2/agents`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: creates an agent record owned by the current app; also sets it as the session's current agent context. Creating an agent does **not** activate it on the app — call `ethora-agents-activate-v2` for that. Idempotent: no — calling twice creates two agents. Failure modes: 401/403 on missing/wrong auth; 422 on field validation failure (e.g. duplicate `slug`, unsupported `llmProvider`/`llmModel`). Returns: the created agent including its id.
ethora-agents-update-v2Update fields on an existing reusable saved agent (`PUT /v2/agents/:agentId`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: **partial update** — only the fields you pass change; omitted fields keep their values. Also sets this agent as the session's current agent context. If the agent is currently activated on the app, changes take effect on the live bot. Idempotent: yes — re-sending the same values is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app; 422 on field validation failure. Get `agentId` from `ethora-agents-list-v2`.
ethora-agents-clone-v2Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (`POST /v2/agents/:agentId/clone`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: creates a new agent record copying the source agent's config; also sets the new agent as the session's current agent context. The source agent is unchanged. Idempotent: no — calling twice creates two clones. Failure modes: 401/403 on missing/wrong auth; 404 if the source `agentId` doesn't exist; 422 if an overridden `slug` collides. When to use: branch a working agent before experimenting, instead of mutating the original with `ethora-agents-update-v2`.
ethora-agents-activate-v2Bind a saved agent as the active AI bot for the current app — copies the agent's config onto the app's bot (`POST /v2/agents/:agentId/activate`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: the app's live bot now uses this agent's prompt/LLM/RAG/identity. Replaces whatever bot config was there before. Also sets this agent as the session's current agent context. Does not by itself set `status: "on"` if the bot was off — pair with `ethora-bot-enable-v2` if needed. Idempotent: yes — activating the already-active agent is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app. Verify with `ethora-bot-get-v2` afterwards.
ethora-chats-message-v2Send a message through the app's chat/bot automation surface — useful for testing the bot or driving automated conversations. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Your Ethora backend must expose the chat automation surface on the same API host. Side effects: posts a real message into the app — in `private` mode to a 1:1 automation session keyed by `nickname`, in `group` mode into the room identified by `roomJid`. If the app's bot is enabled it will react to the message. Idempotent: no — each call posts another message. Failure modes: 401/403 on missing/wrong auth; 400 if `mode` is `group` but no `roomJid` is given (or `private` but no `nickname`); 404 if `roomJid` doesn't exist. Read back the resulting conversation with `ethora-chats-history-v2`. `ethora-bot-message-v2` is an identical alias.
ethora-chats-history-v2Read the persisted message history of a chat automation session — the conversation produced by `ethora-chats-message-v2` and the bot's replies. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete; 404 if the room/session doesn't exist. Returns: the most recent messages (up to `limit`) for the identified session. `ethora-bot-history-v2` is an identical alias.
ethora-bot-message-v2Compatibility alias for `ethora-chats-message-v2` — identical behavior, kept for clients that expect a `bot-`prefixed name. Send a message through the app's chat/bot automation surface. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: posts a real message into the app; the enabled bot will react to it. Not idempotent — each call posts another message. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete. Prefer `ethora-chats-message-v2` in new integrations.
ethora-bot-history-v2Compatibility alias for `ethora-chats-history-v2` — identical behavior, kept for clients that expect a `bot-`prefixed name. Read the persisted message history of a chat automation session. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete. Prefer `ethora-chats-history-v2` in new integrations.
ethora.b2b.auth.useDot-namespaced alias for `ethora-auth-use-b2b` — switches the session's active auth mode to B2B (`x-custom-token`). Auth: requires a `b2bToken` to already be configured. Side effects: session state only; no API call. Idempotent: yes. Provided to reduce auth-mode mistakes for agents that prefer dotted names; behavior is identical to `ethora-auth-use-b2b`.
ethora.b2b.app.createDot-namespaced alias for `ethora-b2b-app-create` — create a new Ethora app server-side. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: provisions a new app record owned by the B2B tenant and allocates a fresh `appId`. Not idempotent — each call creates a new app. Failure modes: 401/403 if not in B2B mode; 422 on an invalid `displayName`. Provided for agents that prefer dotted names. Prefer `ethora-b2b-app-create` in new integrations.
ethora.b2b.bot.enableDot-namespaced alias for `ethora-b2b-bot-enable` — turn on the AI bot for an app (sets `botStatus: "on"`). Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: flips the app's bot status to on; the backend then makes a best-effort activation. The bot only responds if a prompt + LLM are configured and the backend has an AI service set up. Idempotent: yes — enabling an already-on bot is a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is invalid; 400 if no `appId` is given and none is selected. Provided for agents that prefer dotted names. Prefer `ethora-b2b-bot-enable` in new integrations.
ethora.b2b.broadcast.waitDot-namespaced sibling of `ethora-wait-broadcast-job-v2` — block until a broadcast job reaches a terminal state (`completed` / `failed`) or until a timeout. Auth: app-token mode (despite the `b2b` in the name, this variant uses app-token auth — `ethora-app-select` + `ethora-auth-use-app`). Use `ethora-wait-broadcast-job-v2` if you need the B2B-with-explicit-appId path. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in app-token mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` on timeout.
ethora.b2b.app.bootstrap-aiDot-namespaced alias for `ethora-b2b-app-bootstrap-ai` — one-call B2B orchestrator: create an app, index RAG sources, then configure and enable its AI bot. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: runs multiple real operations in sequence (app create, source ingest, bot configure/enable); source ingestion and bot activation are best-effort, so the app is still created even if a later step fails. Not idempotent — each call creates a new app. Failure modes: aborts with the partial step log if app creation fails; previous auth mode restored best-effort on error. Returns: a per-step result log including the new `appId`. Provided for agents that prefer dotted names; behavior matches `ethora-b2b-app-bootstrap-ai`.
ethora-b2b-app-bootstrap-aiOne-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Internally switches into app-token mode for the source-ingest steps and (if `setAsCurrent`) leaves the session pointed at the new app. Side effects: runs multiple real operations in sequence — `appCreate` (B2B), set current app, `/v2/sources/*` ingest (app-token), bot configure/enable. Source ingestion and bot activation are **best-effort**: the app is still created even if a later step fails. The crawl/embedding work continues asynchronously after this returns. Idempotent: no — each call creates a brand-new app. Failure modes: aborts and returns the partial step log if app creation fails; on a later-step failure the previous auth mode is restored best-effort. Bot activation needs an AI service configured on your Ethora backend. Returns: a per-step result log including the new `appId`. For the rooms+tokens variant use `ethora-b2b-app-provision`; for full manual control wire `ethora-b2b-app-create` + `ethora-sources-*-v2` + `ethora-bot-update-v2` yourself.
ethora-generate-chat-component-app-tsxGenerate a ready-to-paste React `App.tsx` snippet that mounts `@ethora/chat-component`. Auth: none required — this is a pure code generator, makes no API calls. Side effects: none — returns the snippet as text; **does not write any file**. Idempotent: yes — same inputs produce the same snippet. Failure modes: effectively none. Returns: `{ filename: "App.tsx", snippet }`. Any values you don't pass are emitted as clearly-marked placeholders. Security note: the snippet includes `appToken` inline only as a quickstart convenience — do not ship hardcoded tokens to production; have your backend issue short-lived credentials instead.
ethora-generate-env-examplesGenerate `.env.example` templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. Auth: none required — pure text generator, makes no API calls. Side effects: none — returns templates as text; **does not write any file**. Idempotent: yes. Failure modes: effectively none. Returns: a single `{ target, template }` when `target` is given, or `{ templates }` with all three when omitted. Templates contain placeholder values and inline security notes only — never real credentials.
ethora-generate-b2b-bootstrap-runbookGenerate a human-readable runbook listing this server's tool calls in the right order for a B2B bootstrap, with example payloads. Auth: none required — pure text generator, makes no API calls and runs nothing. Side effects: none — returns the runbook as text; **does not write any file or execute any step**. Idempotent: yes. Failure modes: effectively none. Returns: the runbook text with your supplied values substituted into the example payloads. This is documentation only — to actually run the sequence use `ethora-run-recipe`, or the one-call orchestrators `ethora-b2b-app-bootstrap-ai` / `ethora-b2b-app-provision`.
| ethora-files-upload-v2 | Upload one or more files to the authenticated user's Ethora file storage (`POST /v2/files`). Auth: user-auth mode with an active user session (`ethora-user-login` first). Side effects: creates file records server-side owned by the logged-in user; each upload is a new record (no overwrite-by-name). Idempotent: no — re-uploading creates duplicate records. Input design: files are passed as base64 so the MCP server never touches your local filesystem. Client-side guardrail rejects any single file over 50MB before upload; the Ethora server enforces its own limits too. Failure modes: 401 if not logged in; 413 if the server's size limit is exceeded; 422 on an unsupported mime type. Per-call limit: 1–5 files. Returns: the created file records (with ids). Manage them with `ethora-files-get-v2` and `ethora-files-delete-v2`. | |
| ethora-files-get-v2 | List the authenticated user's files, or fetch one file's metadata by id (`GET /v2/files`). Auth: user-auth mode with an active user session. Side effects: none — read-only. Idempotent: yes. Failure modes: 401 if not logged in; 404 if a specific `id` is given but not found / not owned by the user. Returns: an array of file records when `id` is omitted, or a single record when `id` is given. Use the ids with `ethora-files-delete-v2`. | |
| ethora-files-delete-v2 | Permanently delete one of the authenticated user's files by id (`DELETE /v2/files/:id`). Auth: user-auth mode with an active user session. Side effects: removes the file record and its stored content. Not reversible. Idempotent: yes after success — a second call returns 404. Failure modes: 401 if not logged in; 403 if the file is not owned by the user; 404 if the `id` does not exist. Get ids from `ethora-files-get-v2`. | |
| ethora-sources-site-crawl | Crawl a website URL and ingest its content into an app's RAG sources, so the app's AI bot can answer from it (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a crawl + embedding job on the server; pages become queryable RAG context once indexing finishes (not synchronous). With `followLink: true` the crawler also follows in-domain links, which can ingest many pages. Idempotent: no — re-crawling the same URL adds/updates source records; combined with `followLink` it can fan out broadly. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-reindex` (refresh), `ethora-sources-site-delete-url` (remove), `ethora-sources-docs-upload` (ingest documents instead of a URL). For app-token / B2B flows use `ethora-sources-site-crawl-v2`. | |
| ethora-sources-site-reindex | Re-crawl and re-embed a previously crawled URL by its `urlId`, refreshing the RAG content for that page (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a refresh job on the server; the page's existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes the same record again. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` or `urlId` is unknown. When to use: the source page changed and you want the bot to pick up the new content. Get `urlId` values from `ethora-sources-site-list-v2`. For app-token / B2B flows use `ethora-sources-site-reindex-v2`. | |
| ethora-sources-site-delete-url | Remove a single crawled URL from an app's RAG sources, matched by its exact url string (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes the source record and its embeddings; the app's bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if the exact `url` string isn't a crawled source. Note: matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several at once use `ethora-sources-site-delete-records-v1`. | |
| ethora-sources-site-delete-records-v1 | Bulk-remove crawled URLs from an app's RAG sources in one call, matched by exact url strings (legacy owner/admin user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes each matching source record and its embeddings. Not reversible. Idempotent: yes — URLs not present are skipped. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` is invalid. Per-call limit: 1–100 URLs. When to use: cleaning up many pages at once. For the single-URL variant use `ethora-sources-site-delete-url`; for app-token / B2B flows use `ethora-sources-site-delete-url-v2-batch`. | |
| ethora-sources-docs-upload | Upload documents (PDF, text, etc.) into an app's RAG sources so the app's AI bot can answer from them (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-delete` (remove), `ethora-sources-site-crawl` (ingest a URL instead). For app-token / B2B flows use `ethora-sources-docs-upload-v2`. | |
| ethora-sources-docs-delete | Remove a previously ingested document from an app's RAG sources by `docId` (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes the document record and its embeddings; the app's bot can no longer answer from it. Not reversible (re-add via `ethora-sources-docs-upload`). Idempotent: yes after success — a second call returns 404. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`. For app-token / B2B flows use `ethora-sources-docs-delete-v2`. | |
| ethora-sources-site-crawl-v2 | Crawl a website URL and ingest its content into an app's RAG sources (app-token / B2B variant of `ethora-sources-site-crawl`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a crawl + embedding job; pages become queryable RAG context once indexing finishes (not synchronous — this returns once the job is accepted). With `followLink: true` the crawler also follows in-domain links and can ingest many pages. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-crawl-v2-wait` (block until done), `ethora-sources-site-list-v2` (see results), `ethora-sources-site-reindex-v2` (refresh), `ethora-sources-site-delete-url-v2` (remove). | |
| ethora-sources-site-reindex-v2 | 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`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a refresh job; the existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes again. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown. Get `urlId` values from `ethora-sources-site-list-v2`. Use `ethora-sources-site-reindex-v2-wait` to block until done. | |
| ethora-sources-site-crawl-v2-wait | Crawl a website URL and block until the server finishes the request — a single-call, long-timeout variant of `ethora-sources-site-crawl-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-crawl-v2` (crawl + embed into RAG sources), but this MCP call blocks for up to `timeoutMs` waiting for the server's response instead of returning as soon as the job is accepted. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 504/timeout if the crawl takes longer than `timeoutMs` (the job may still complete server-side — check with `ethora-sources-site-list-v2`). Returns: `{ done: true, durationMs, result }`. Use the non-wait `ethora-sources-site-crawl-v2` if you'd rather not block. | |
| ethora-sources-site-reindex-v2-wait | Re-crawl and re-embed a previously crawled URL and block until the server finishes — a single-call, long-timeout variant of `ethora-sources-site-reindex-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-reindex-v2` (refresh the source record's RAG content), but this MCP call blocks for up to `timeoutMs`. Idempotent: effectively yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side). Returns: `{ done: true, durationMs, result }`. Get `urlId` values from `ethora-sources-site-list-v2`. | |
| ethora-sources-site-list-v2 | List an app's crawled website sources, including each source's id, URL, and current RAG tags. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; returns an empty list if nothing has been crawled. Returns: site source records. Their ids feed `ethora-sources-site-tags-update-v2`, `ethora-sources-site-delete-url-v2-batch`, and `ethora-sources-site-reindex-v2` (`urlId`). | |
| ethora-sources-site-tags-update-v2 | Set the RAG retrieval tags on a crawled website source. Tags let the bot's `ragTags` setting narrow which sources it retrieves from. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **replaces** the source's tag set with the provided `tags` array (it is not additive — pass the full desired set, or an empty array to clear all tags). Idempotent: yes — re-sending the same tags is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `sourceId` is unknown. Get `sourceId` values from `ethora-sources-site-list-v2`. The doc equivalent is `ethora-sources-docs-tags-update-v2`. | |
| ethora-sources-site-delete-url-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`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deletes the source record and its embeddings; the bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl-v2`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401/403 on missing/wrong auth; 404 if the exact `url` isn't a crawled source. Matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several by id use `ethora-sources-site-delete-url-v2-batch`. | |
| ethora-sources-docs-upload-v2 | Upload documents (PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-sources-docs-upload`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-list-v2` (see results), `ethora-sources-docs-delete-v2` (remove), `ethora-sources-docs-tags-update-v2` (tag). | |
| ethora-sources-docs-list-v2 | List an app's ingested documents, including each document's id, name, and current RAG tags. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; returns an empty list if nothing has been uploaded. Returns: document records. Their ids feed `ethora-sources-docs-tags-update-v2` and `ethora-sources-docs-delete-v2`. The website-sources equivalent is `ethora-sources-site-list-v2`. | |
| ethora-sources-docs-tags-update-v2 | Set the RAG retrieval tags on an ingested document. Tags let the bot's `ragTags` setting narrow which sources it retrieves from. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **replaces** the document's tag set with the provided `tags` array (it is not additive — pass the full desired set, or an empty array to clear all tags). Idempotent: yes — re-sending the same tags is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`. The website-source equivalent is `ethora-sources-site-tags-update-v2`. | |
| ethora-sources-docs-delete-v2 | Remove a previously ingested document from an app's RAG sources by `docId` (app-token / B2B variant of `ethora-sources-docs-delete`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deletes the document record and its embeddings; the bot can no longer answer from it. Not reversible (re-add via `ethora-sources-docs-upload-v2`). Idempotent: yes after success — a second call returns 404. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `docId` is unknown. Get `docId` values from `ethora-sources-docs-list-v2`. | |
| ethora-users-batch-create-v2 | Provision many Ethora users in one asynchronous batch job — the bulk equivalent of `ethora-user-register`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: enqueues a background job (server responds HTTP 202) — users are **not** created synchronously. Each user is created under the B2B tenant's app. With `bypassEmailConfirmation: true` users are usable immediately; otherwise each receives a verification email. Idempotent: no — re-running re-attempts creation; the job itself reports per-user conflicts (already-registered emails) rather than failing the whole batch. Failure modes: 401/403 if not in B2B mode; 422 if the `usersList` fails validation. Per-call limit: 1–100 users. Returns: `{ jobId, statusUrl }`. Track it with `ethora-users-batch-job-v2` (one-shot) or `ethora-wait-users-batch-job-v2` (poll to completion). | |
| ethora-users-batch-job-v2 | Fetch the current status and per-user results of a users batch job by `jobId` (one-shot, no polling). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: the job object including its `state` (`pending` / `running` / `completed` / `failed`) and per-user outcomes (created / conflict / error). For a blocking wait-until-done, use `ethora-wait-users-batch-job-v2`. | |
| ethora-wait-users-batch-job-v2 | Block until a users batch job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-users-batch-job-v2` calls. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-users-batch-job-v2`). | |
| ethora-app-tokens-list-v2 | List the app tokens issued for an app — **metadata only**, the secret token values are never returned. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 400 if no `appId` is given and none is selected; 404 if `appId` is invalid. Returns: token records with `tokenId`, label, created/rotated timestamps, and status. The actual token strings are only ever shown once, at create/rotate time (`ethora-app-tokens-create-v2`, `ethora-app-tokens-rotate-v2`). | |
| ethora-app-tokens-create-v2 | Mint a new app token for an app. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: creates a new app token server-side. **The secret token value is returned exactly once in this response and cannot be retrieved again** — capture it immediately (e.g. store it, or pass it to `ethora-app-select`). Idempotent: no — each call mints a distinct token. Failure modes: 401/403 if not in B2B mode; 400 if no `appId` is given and none is selected; 404 if `appId` is invalid. Returns: the new token including its one-time secret value and its `tokenId`. Manage it later with `ethora-app-tokens-list-v2`, `ethora-app-tokens-rotate-v2`, `ethora-app-tokens-revoke-v2`. | |
| ethora-app-tokens-rotate-v2 | Rotate an app token: revoke an existing token and issue a replacement in one step. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: the old `tokenId` is revoked **immediately** — anything still using it stops working at once — and a new token is created. **The new secret value is returned exactly once** — capture it immediately. Idempotent: no — each call revokes and re-issues. Failure modes: 401/403 if not in B2B mode; 404 if `appId` or `tokenId` is unknown; 400 if no `appId` is given and none is selected. Returns: the new token including its one-time secret value and `tokenId`. Use `ethora-app-tokens-revoke-v2` if you only want to revoke without a replacement. | |
| ethora-app-tokens-revoke-v2 | Permanently revoke an app token by `tokenId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: the token stops working **immediately** — any client, SDK, or MCP session still using it will start getting auth failures. No replacement is issued (use `ethora-app-tokens-rotate-v2` for revoke-and-replace). Idempotent: yes — revoking an already-revoked token succeeds as a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is unknown; 400 if no `appId` is given and none is selected. Get `tokenId` values from `ethora-app-tokens-list-v2`. | |
| ethora-b2b-app-provision | One-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Internally uses the first minted app token for the bot/room steps. Side effects: runs several real operations in sequence — `appCreate` (B2B), `app-tokens-create` (×N), room creation (×N), bot configure/enable. Returns a per-step log; later-step failures don't undo earlier steps (the app and any tokens already exist). Idempotent: no — each call creates a new app, new tokens, and new rooms. Failure modes: aborts with the partial step log if app creation fails; the previous auth mode is restored best-effort on error. Returns: a per-step result log including `appId` and the created tokens (tokens are returned **once** — capture them). Sibling orchestrator `ethora-b2b-app-bootstrap-ai` does sources+bot but not tokens/rooms. | |
| ethora-user-login | Authenticate as an existing Ethora user with email + password. Auth: user-auth mode (call `ethora-auth-use-user` first) and a configured `appJwt` (env or `ethora-configure`). Side effects: stores the resulting user session token in this MCP session; unlocks user-auth tools (`ethora-app-list`, `ethora-app-create`, `ethora-files-*`, `ethora-wallet-*`). Idempotent: yes — safe to retry on transport failures. Failure modes: 401/403 on bad credentials; 404 if the email isn't registered; 429 if the Ethora server's per-IP login rate limit is hit (retry with backoff). Related: `ethora-user-register` (create account first), `ethora-auth-use-user` (switch mode), `ethora-status` (verify session). | |
| ethora-user-register | Register a new Ethora end-user account by email + first/last name. Auth: user-auth mode and a configured `appJwt` (env or `ethora-configure`) — the JWT tells the server which app the new user belongs to. Side effects: creates a pending user record on the Ethora server and triggers a verification email to the address; the user must click the link in that email before `ethora-user-login` will succeed. Idempotent: safe to retry on transport failures (server deduplicates by email within an app). Calling twice with a fresh email creates one account; calling with an already-registered email returns 422. Failure modes: 422 with a validation error if the email is already registered, if names violate server rules, or if the configured `appJwt` is invalid; 401 if no `appJwt` is configured. When to use: end-user self-serve sign-up flows. For bulk B2B user provisioning prefer `ethora-users-batch-create-v2`. | |
| ethora-app-list | List all Ethora apps (tenants) owned by the currently logged-in user. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: none — read-only. Idempotent: yes — repeated calls return the same set unless an app is created/deleted in between. Failure modes: 401 if not logged in; returns an empty list if the user owns no apps. Returns: an array where each entry includes `appId` (24-char hex ObjectId), `displayName`, `domainName`, ownership and bot-status metadata. Pass `appId` into `ethora-app-update`, `ethora-app-delete`, or `ethora-app-select` for app-scoped flows. | |
| ethora-app-create | Create a new Ethora app (tenant) owned by the currently logged-in user. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: provisions a new app record on the server, allocates a fresh 24-char hex `appId`, sets the caller as owner. Each app counts against the owner's plan limit. Idempotent: no — calling twice creates two apps. Use `ethora-app-list` first if you want to reuse an existing app. Failure modes: 401 if not logged in; 402/403 if the owner's plan limit is reached; 422 if `displayName` violates server rules. Returns: the new app object including `appId`. Pass it to `ethora-app-update` (set domainName/colors/bot), `ethora-app-select` (switch into app-token flows), or `ethora-app-delete` (remove). When to use: interactive setup by a logged-in user. For server-to-server provisioning prefer `ethora-b2b-app-create` or the one-call orchestrator `ethora-b2b-app-bootstrap-ai`. | |
| ethora-app-update | Update mutable fields on an existing Ethora app the caller owns (displayName, domainName, appDescription, primaryColor, botStatus). Auth: user-auth mode and an active user session; the caller must own the app. Side effects: **partial update** — only the fields you pass are changed; omitted fields keep their previous values. `domainName` changes affect the public URL (`<domain>.ethora.com`) immediately. `botStatus: "on"` enables the bot only if the app has a configured prompt (use `ethora-bot-update-v2` / `ethora-bot-enable-v2` for the AI bot lifecycle). Idempotent: yes — repeating an update with the same values is a no-op. Failure modes: 401 if not logged in; 403 if not the owner; 404 if `appId` is invalid; 422 on field validation failure (e.g. `domainName` already taken, `primaryColor` not in `#RRGGBB` format). When to use: change branding, route the web app under a custom subdomain, or quickly toggle the bot on/off without re-running setup. | |
| ethora-app-get-default-rooms | List the default chat rooms (MUC rooms) of the currently selected Ethora app — every new user of the app auto-joins these. Auth: user-auth mode and an active user session. Operates against the currently selected app — call `ethora-app-select` first, or use `ethora-app-get-default-rooms-with-app-id` to pass `appId` explicitly. Side effects: none — read-only. Idempotent: yes. Failure modes: 400 if no app is currently selected in this MCP session; 401 if not logged in. Returns: array of rooms with their JIDs and titles. Use the JIDs with `ethora-chats-broadcast-v2`, `ethora-app-create-chat` (add more), or `ethora-app-delete-chat` (remove). | |
| ethora-app-create-chat | Create a new chat room (MUC room) inside an Ethora app the caller owns. Auth: user-auth mode and an active user session; the caller must own the app. Side effects: provisions a new MUC room with the given `title`. If `pinned: true` the room is added to the app's default rooms list — every new user of the app will auto-join it from that point on. Existing users are **not** auto-added; for that, see the chat membership v2 endpoints. Idempotent: no — calling twice with the same title creates two distinct rooms with different JIDs. Failure modes: 401 if not logged in; 403 if the caller does not own the app; 404 if `appId` is invalid; 422 if `title` is empty or violates server rules. Returns: the new room object including its JID. Use the JID with `ethora-chats-broadcast-v2` to send messages or `ethora-app-delete-chat` to remove. | |
| ethora-app-delete-chat | Permanently delete a chat room from an Ethora app the caller owns. **Destructive and irreversible.** Gated behind `ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true`; the tool refuses to register otherwise. Auth: user-auth mode and an active user session; the caller must own the app. Side effects: removes the MUC room, its message archive, and all member affiliations. Participants will see "room destroyed" on their next reconnect. Idempotent: yes after success — subsequent calls return 404. Failure modes: 401 if not logged in; 403 if not the owner; 404 if `chatJid` is not a room in the app. When to use: explicit room tear-down. To remove only from the default rooms list (without destroying the room) update the default-rooms config rather than deleting. | |
| ethora-app-get-default-rooms-with-app-id | List the default chat rooms of a specific Ethora app, passed via `appId` (or defaulted to the currently selected app). Auth: user-auth mode and an active user session. The caller must have read access to the app — either ownership, or membership of at least one of its rooms. Side effects: none — read-only. Idempotent: yes. Failure modes: 400 if neither `appId` is passed nor an app is currently selected; 401 if not logged in; 403 if the caller lacks read access; 404 if `appId` does not exist. Returns: array of rooms with their JIDs and titles. Use `ethora-app-get-default-rooms` for the simpler "current app only" variant. | |
| ethora-wallet-get-balance | Read the on-chain wallet balance for the currently authenticated user, across the ERC-20 token(s) the Ethora backend tracks for them. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: none — read-only, no gas consumed. Idempotent: yes — safe to call repeatedly. Failure modes: 401 if not logged in; 503 if the wallet RPC is temporarily unreachable (safe to retry on 503 with backoff). Returns: balances in the units the Ethora backend reports (typically whole-token integers — confirm with your deployment). Pair with `ethora-wallet-erc20-transfer` to spend. | |
| ethora-b2b-app-create | Create a new Ethora app (tenant) server-side using B2B auth — the partner/integrator equivalent of `ethora-app-create`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: provisions a new app record owned by the B2B tenant and allocates a fresh 24-char hex `appId`. Does not create tokens, rooms, or a bot. Idempotent: no — calling twice creates two apps. Failure modes: 401/403 if not in B2B mode or the `b2bToken` is invalid; 422 if `displayName` violates server rules. Returns: the new app object including `appId`. Next steps: `ethora-app-tokens-create-v2` (mint an appToken), `ethora-app-select` (set context), `ethora-bot-update-v2` (configure the bot). For the all-in-one path use `ethora-b2b-app-bootstrap-ai` or `ethora-b2b-app-provision`. | |
| ethora-b2b-bot-enable | Turn on the AI bot for an app via B2B auth (sets `botStatus: "on"` on the app record). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: flips the app's bot status to on; the backend then makes a **best-effort** activation against the configured AI service. The bot only actually responds if the app already has a prompt + LLM configured (see `ethora-bot-update-v2`) and the Ethora backend has AI service URL/secret set. Idempotent: yes — enabling an already-enabled bot is a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is invalid; 400 if no `appId` is given and none is selected. Note: this is a thin convenience over `ethora-app-update`. For full bot configuration (prompt, LLM, RAG, greeting) use `ethora-bot-update-v2`; `ethora-bot-enable-v2` is the app-token-friendly equivalent. | |
| ethora-bot-get-v2 | Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Returns: the bot settings object. Use it to inspect before changing things with `ethora-bot-update-v2`, or to confirm an `ethora-agents-activate-v2` took effect. | |
| ethora-bot-update-v2 | Configure the AI bot for an app — its prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **partial update** — only the fields you pass are changed; omitted fields keep their values. Setting `status: "on"` activates the bot (best-effort against the configured AI service — needs a prompt + LLM and a backend AI service configured). Idempotent: yes — re-sending the same values is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; 422 on field validation failure (e.g. an `llmProvider`/`llmModel` your backend doesn't have enabled). Related: `ethora-bot-get-v2` (inspect first), `ethora-bot-enable-v2` / `ethora-bot-disable-v2` (just toggle status), `ethora-agents-activate-v2` (apply a saved agent's config instead of setting fields by hand). | |
| ethora-bot-enable-v2 | Turn the AI bot on for an app (sets bot `status: "on"`), optionally setting its trigger at the same time. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: activates the bot. It only actually responds if a prompt + LLM are configured (see `ethora-bot-update-v2` or `ethora-agents-activate-v2`) and the Ethora backend has an AI service configured. Idempotent: yes — enabling an already-on bot is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Thin convenience over `ethora-bot-update-v2` for the common "just turn it on" case. Pair with `ethora-bot-disable-v2` to turn it off. | |
| ethora-bot-disable-v2 | Turn the AI bot off for an app (sets bot `status: "off"`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deactivates the bot — it stops responding to messages. The bot's configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling later restores the same behavior. Idempotent: yes — disabling an already-off bot is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid. Thin convenience over `ethora-bot-update-v2`. Pair with `ethora-bot-enable-v2` to turn it back on. | |
| ethora-bot-widget-v2 | Read the public chat-widget / embed configuration for the current app's bot (`GET /v2/bot/widget`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in app-token mode or the appToken is invalid. Returns: the widget config and the public widget URL metadata — what you need to embed the bot on a website. To enable/disable the public widget, set `widgetPublicEnabled` via `ethora-bot-update-v2`. | |
| ethora-agents-list-v2 | List the reusable saved agents owned by the current app (`GET /v2/agents`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in app-token mode or the appToken is invalid; returns an empty list if the app has no saved agents. Returns: an array of agents with their ids, names, and config. A saved agent is a reusable bot definition — use the ids with `ethora-agents-get-v2`, `ethora-agents-update-v2`, `ethora-agents-clone-v2`, or `ethora-agents-activate-v2`. | |
| ethora-agents-get-v2 | Fetch one reusable saved agent's full config by id (`GET /v2/agents/:agentId`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: also sets this agent as the current agent context for the session (so later agent tools can omit `agentId`). No server-side change. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app. Returns: the agent object (prompt, LLM, RAG settings, visibility, etc.). Get ids from `ethora-agents-list-v2`. | |
| ethora-agents-create-v2 | Create a new reusable saved agent — a named, reusable bot definition (prompt + LLM + RAG settings + identity) that can later be activated onto any app (`POST /v2/agents`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: creates an agent record owned by the current app; also sets it as the session's current agent context. Creating an agent does **not** activate it on the app — call `ethora-agents-activate-v2` for that. Idempotent: no — calling twice creates two agents. Failure modes: 401/403 on missing/wrong auth; 422 on field validation failure (e.g. duplicate `slug`, unsupported `llmProvider`/`llmModel`). Returns: the created agent including its id. | |
| ethora-agents-update-v2 | Update fields on an existing reusable saved agent (`PUT /v2/agents/:agentId`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: **partial update** — only the fields you pass change; omitted fields keep their values. Also sets this agent as the session's current agent context. If the agent is currently activated on the app, changes take effect on the live bot. Idempotent: yes — re-sending the same values is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app; 422 on field validation failure. Get `agentId` from `ethora-agents-list-v2`. | |
| ethora-agents-clone-v2 | Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (`POST /v2/agents/:agentId/clone`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: creates a new agent record copying the source agent's config; also sets the new agent as the session's current agent context. The source agent is unchanged. Idempotent: no — calling twice creates two clones. Failure modes: 401/403 on missing/wrong auth; 404 if the source `agentId` doesn't exist; 422 if an overridden `slug` collides. When to use: branch a working agent before experimenting, instead of mutating the original with `ethora-agents-update-v2`. | |
| ethora-agents-activate-v2 | Bind a saved agent as the active AI bot for the current app — copies the agent's config onto the app's bot (`POST /v2/agents/:agentId/activate`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: the app's live bot now uses this agent's prompt/LLM/RAG/identity. Replaces whatever bot config was there before. Also sets this agent as the session's current agent context. Does not by itself set `status: "on"` if the bot was off — pair with `ethora-bot-enable-v2` if needed. Idempotent: yes — activating the already-active agent is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `agentId` is not an agent of the current app. Verify with `ethora-bot-get-v2` afterwards. | |
| ethora-chats-message-v2 | Send a message through the app's chat/bot automation surface — useful for testing the bot or driving automated conversations. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Your Ethora backend must expose the chat automation surface on the same API host. Side effects: posts a real message into the app — in `private` mode to a 1:1 automation session keyed by `nickname`, in `group` mode into the room identified by `roomJid`. If the app's bot is enabled it will react to the message. Idempotent: no — each call posts another message. Failure modes: 401/403 on missing/wrong auth; 400 if `mode` is `group` but no `roomJid` is given (or `private` but no `nickname`); 404 if `roomJid` doesn't exist. Read back the resulting conversation with `ethora-chats-history-v2`. `ethora-bot-message-v2` is an identical alias. | |
| ethora-chats-history-v2 | Read the persisted message history of a chat automation session — the conversation produced by `ethora-chats-message-v2` and the bot's replies. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete; 404 if the room/session doesn't exist. Returns: the most recent messages (up to `limit`) for the identified session. `ethora-bot-history-v2` is an identical alias. | |
| ethora-bot-message-v2 | Compatibility alias for `ethora-chats-message-v2` — identical behavior, kept for clients that expect a `bot-`prefixed name. Send a message through the app's chat/bot automation surface. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: posts a real message into the app; the enabled bot will react to it. Not idempotent — each call posts another message. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete. Prefer `ethora-chats-message-v2` in new integrations. | |
| ethora-bot-history-v2 | Compatibility alias for `ethora-chats-history-v2` — identical behavior, kept for clients that expect a `bot-`prefixed name. Read the persisted message history of a chat automation session. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 400 if the `mode`/`nickname`/`roomJid` combination is incomplete. Prefer `ethora-chats-history-v2` in new integrations. | |
| ethora.b2b.auth.use | Dot-namespaced alias for `ethora-auth-use-b2b` — switches the session's active auth mode to B2B (`x-custom-token`). Auth: requires a `b2bToken` to already be configured. Side effects: session state only; no API call. Idempotent: yes. Provided to reduce auth-mode mistakes for agents that prefer dotted names; behavior is identical to `ethora-auth-use-b2b`. | |
| ethora.b2b.app.create | Dot-namespaced alias for `ethora-b2b-app-create` — create a new Ethora app server-side. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: provisions a new app record owned by the B2B tenant and allocates a fresh `appId`. Not idempotent — each call creates a new app. Failure modes: 401/403 if not in B2B mode; 422 on an invalid `displayName`. Provided for agents that prefer dotted names. Prefer `ethora-b2b-app-create` in new integrations. | |
| ethora.b2b.bot.enable | Dot-namespaced alias for `ethora-b2b-bot-enable` — turn on the AI bot for an app (sets `botStatus: "on"`). Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: flips the app's bot status to on; the backend then makes a best-effort activation. The bot only responds if a prompt + LLM are configured and the backend has an AI service set up. Idempotent: yes — enabling an already-on bot is a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is invalid; 400 if no `appId` is given and none is selected. Provided for agents that prefer dotted names. Prefer `ethora-b2b-bot-enable` in new integrations. | |
| ethora.b2b.broadcast.wait | Dot-namespaced sibling of `ethora-wait-broadcast-job-v2` — block until a broadcast job reaches a terminal state (`completed` / `failed`) or until a timeout. Auth: app-token mode (despite the `b2b` in the name, this variant uses app-token auth — `ethora-app-select` + `ethora-auth-use-app`). Use `ethora-wait-broadcast-job-v2` if you need the B2B-with-explicit-appId path. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in app-token mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` on timeout. | |
| ethora.b2b.app.bootstrap-ai | Dot-namespaced alias for `ethora-b2b-app-bootstrap-ai` — one-call B2B orchestrator: create an app, index RAG sources, then configure and enable its AI bot. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: runs multiple real operations in sequence (app create, source ingest, bot configure/enable); source ingestion and bot activation are best-effort, so the app is still created even if a later step fails. Not idempotent — each call creates a new app. Failure modes: aborts with the partial step log if app creation fails; previous auth mode restored best-effort on error. Returns: a per-step result log including the new `appId`. Provided for agents that prefer dotted names; behavior matches `ethora-b2b-app-bootstrap-ai`. | |
| ethora-b2b-app-bootstrap-ai | One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Internally switches into app-token mode for the source-ingest steps and (if `setAsCurrent`) leaves the session pointed at the new app. Side effects: runs multiple real operations in sequence — `appCreate` (B2B), set current app, `/v2/sources/*` ingest (app-token), bot configure/enable. Source ingestion and bot activation are **best-effort**: the app is still created even if a later step fails. The crawl/embedding work continues asynchronously after this returns. Idempotent: no — each call creates a brand-new app. Failure modes: aborts and returns the partial step log if app creation fails; on a later-step failure the previous auth mode is restored best-effort. Bot activation needs an AI service configured on your Ethora backend. Returns: a per-step result log including the new `appId`. For the rooms+tokens variant use `ethora-b2b-app-provision`; for full manual control wire `ethora-b2b-app-create` + `ethora-sources-*-v2` + `ethora-bot-update-v2` yourself. | |
| ethora-generate-chat-component-app-tsx | Generate a ready-to-paste React `App.tsx` snippet that mounts `@ethora/chat-component`. Auth: none required — this is a pure code generator, makes no API calls. Side effects: none — returns the snippet as text; **does not write any file**. Idempotent: yes — same inputs produce the same snippet. Failure modes: effectively none. Returns: `{ filename: "App.tsx", snippet }`. Any values you don't pass are emitted as clearly-marked placeholders. Security note: the snippet includes `appToken` inline only as a quickstart convenience — do not ship hardcoded tokens to production; have your backend issue short-lived credentials instead. | |
| ethora-generate-env-examples | Generate `.env.example` templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. Auth: none required — pure text generator, makes no API calls. Side effects: none — returns templates as text; **does not write any file**. Idempotent: yes. Failure modes: effectively none. Returns: a single `{ target, template }` when `target` is given, or `{ templates }` with all three when omitted. Templates contain placeholder values and inline security notes only — never real credentials. | |
| ethora-generate-b2b-bootstrap-runbook | Generate a human-readable runbook listing this server's tool calls in the right order for a B2B bootstrap, with example payloads. Auth: none required — pure text generator, makes no API calls and runs nothing. Side effects: none — returns the runbook as text; **does not write any file or execute any step**. Idempotent: yes. Failure modes: effectively none. Returns: the runbook text with your supplied values substituted into the example payloads. This is documentation only — to actually run the sequence use `ethora-run-recipe`, or the one-call orchestrators `ethora-b2b-app-bootstrap-ai` / `ethora-b2b-app-provision`. |
Configuration
ETHORA_APP_JWTSecretApp JWT used for the user-auth bootstrap flow (login/register). Usually starts with 'JWT '. Optional; can also be set at runtime via the ethora-configure tool.
ETHORA_B2B_TOKENSecretB2B server token used for tenant-actor x-custom-token auth (JWT with type=server). Required for B2B / app provisioning flows. Optional; can also be set at runtime.
ETHORA_API_URLFull Ethora API URL. Defaults to https://api.chat.ethora.com/v1 if neither ETHORA_API_URL nor ETHORA_BASE_URL is set.
ETHORA_BASE_URLBase host URL (e.g. https://api.chat.ethora.com). The server appends /v1 automatically. Use ETHORA_API_URL instead if you need a non-/v1 path.
ETHORA_MCP_ENABLE_DANGEROUS_TOOLSSet to 'true' to expose destructive tools (app deletion, wallet transfers, bulk delete). Disabled by default.
| Name | Description | |
|---|---|---|
| ETHORA_APP_JWT | App JWT used for the user-auth bootstrap flow (login/register). Usually starts with 'JWT '. Optional; can also be set at runtime via the ethora-configure tool. | Secret |
| ETHORA_B2B_TOKEN | B2B server token used for tenant-actor x-custom-token auth (JWT with type=server). Required for B2B / app provisioning flows. Optional; can also be set at runtime. | Secret |
| ETHORA_API_URL | Full Ethora API URL. Defaults to https://api.chat.ethora.com/v1 if neither ETHORA_API_URL nor ETHORA_BASE_URL is set. | |
| ETHORA_BASE_URL | Base host URL (e.g. https://api.chat.ethora.com). The server appends /v1 automatically. Use ETHORA_API_URL instead if you need a non-/v1 path. | |
| ETHORA_MCP_ENABLE_DANGEROUS_TOOLS | Set to 'true' to expose destructive tools (app deletion, wallet transfers, bulk delete). Disabled by default. |
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledappros/ethora-mcp-cli is public and reachablegithub.com/dappros/ethora-mcp-cli ↗Pass
- Package names this repository as its source@ethora/mcp-server names dappros/ethora-mcp-cli as sourcenpmjs.com/package/@ethora/mcp-server ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/dappros/ethora-mcp-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @ethora/mcp-serverPass
- No critical advisory in the package or its dependencies112 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the modelA tool description points at credential filesFinding
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEthora MCP Server (Model Context Protocol)
Add the hosted server in one click. You sign in through your browser; there is nothing to install and no key to paste.
For Claude.ai, ChatGPT, Claude Desktop, LM Studio and anything else that takes a connector URL, add
https://mcp.chat.ethora.com/mcp/oauth and sign in. Running it yourself instead? See
Using with stdio clients.
The MCP server for Ethora, an open-source chat and messaging platform with a built-in AI agent framework. It lets Claude, ChatGPT, Cursor, Claude Code, VS Code and autonomous agents create Ethora apps, chat rooms, users and AI agents, post messages, index RAG sources and produce website chat-widget embeds, all through tool calls.
Part of the Ethora SDK ecosystem. Cross-SDK updates: Release Notes. Package changes: CHANGELOG.md.
- npm: https://www.npmjs.com/package/@ethora/mcp-server
- MCP Registry:
io.github.dappros/ethora-mcp-server(https://registry.modelcontextprotocol.io/) - Ethora API (Swagger): https://api.chat.ethora.com/api-docs/#/
Three ways to use it
| Where it runs | Best for | |
|---|---|---|
| Hosted (Ethora Cloud) | https://mcp.chat.ethora.com/mcp (production; https://mcp.chat-qa.ethora.com/mcp is the QA instance) |
Claude.ai, ChatGPT, Claude Code, Cursor and agents that talk to Ethora Cloud with no local install |
| Self-hosted | Ships with the Ethora monoserver deploy; enable services.mcp.enabled in deploy.yml and it is served at mcp.<your domain>/mcp |
Dedicated or on-premise Ethora installs; agent traffic never leaves your infrastructure |
| stdio CLI | npx -y @ethora/mcp-server on your machine, configured with env vars |
Local development, CI, and clients that launch a command |
The hosted and self-hosted modes are the same server started with ETHORA_MCP_TRANSPORT=http. Every MCP session has private in-memory state: one client's login, selected app or tokens are never visible to another session.
Account memory. Some clients open a new MCP session for every tool call (ChatGPT does), which would lose the selected app between calls. So the server keeps a small snapshot per signed-in account, keyed by the user id in the bearer token: the current app and agent, the appToken the API handed that account for the current app, and the enabled tool groups. A new session that arrives with a token for the same account (OAuth, personal URL or Bearer header) gets it back, after the token has been validated against the API. Memory lives in the process, expires after 24 hours idle, and never holds the user token itself. Two more defaults close the same gap: ethora-app-create selects the new app, and an account that owns exactly one app has it selected automatically on the first app-scoped call.
60-second quickstart
Claude.ai or ChatGPT (custom connector). In the Ethora web app open Account, then the AI Assistants tab, create an API key and copy the personal connector URL it shows (https://mcp.chat.ethora.com/mcp/k/<key>). Paste it as a custom connector. Every conversation is authenticated with no login step. For a listed connector that uses the vendor's OAuth login instead, the URL is https://mcp.chat.ethora.com/mcp/oauth.
Claude Code.
# with a personal connector URL (no headers needed)
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp/k/<your API key>
# or the open endpoint plus a Bearer header
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp --header "Authorization: Bearer <your API key>"
Cursor, VS Code, and any client that takes a URL and headers.
{
"mcpServers": {
"ethora": {
"url": "https://mcp.chat.ethora.com/mcp",
"headers": { "Authorization": "Bearer <your API key>" }
}
}
}
Autonomous agents with no account yet. Connect to https://mcp.chat.ethora.com/mcp with no credentials and call ethora-user-register with an email, first and last name. It creates the account, logs the session in, and returns a generated password plus an API key and connectorUrl exactly once. Store the key and reconnect later with the Bearer header or the personal URL; nothing else is needed, no browser and no email confirmation.
stdio CLI.
ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-server
Then ask your agent to call ethora-status, ethora-user-login (or ethora-user-register) and ethora-app-list. Lost at any point, call ethora-help: it reads the current state and returns the recommended next calls.
Entry points and authentication
| Entry point | Who supplies identity | Typical client |
|---|---|---|
/mcp (add ?tools=all to list every tool up front) |
Nobody at connect time. Call ethora-user-login or ethora-user-register inside the session, or send Authorization: Bearer <token> on every request (user API key, app token or B2B token; the server picks the auth mode from the token type) |
Agents, Claude Code, Cursor, connectors added as "no auth" |
/mcp/k/<api-key> |
The key in the path, applied like a Bearer header | Claude.ai and ChatGPT custom connectors, which take a URL but no headers |
/mcp/oauth |
An OAuth 2.1 access token obtained through the Ethora authorization server (dynamic client registration, PKCE, access scopes read, write, admin, plus the identity scopes openid and email for directories that require them) |
Connector directories (Claude, ChatGPT); vendors run the login flow themselves |
| stdio | Env vars ETHORA_APP_JWT (login/register bootstrap) and optional ETHORA_B2B_TOKEN, or ethora-session-configure at runtime |
Local CLI |
Stay in user auth mode on the hosted server (ethora-status shows authMode: user). App-token and B2B modes exist for server integrations; the agents and rooms routes reject app tokens.
API keys
ethora-api-key-create { name?, ttlDays? }mints a key (default 90 days, max 365), shown once together withconnectorUrl.ethora-user-registermints one by default andethora-user-login { createApiKey: true }on request.ethora-api-key-listshows id, name, created and expiry, never the value.ethora-api-key-revoke { id }invalidates it immediately: the next request with that key fails withREFRESH_RECORD_NOT_FOUND.- The same keys are managed in the Ethora web app under Account, AI Assistants, where the personal URL, a Claude Code one-liner and a Cursor config are shown with copy buttons.
- A key acts as the user. Treat the personal URL like a password: do not share screenshots of it, revoke it if it leaks. The server never logs request URLs, and the monoserver nginx template logs method and status only on the MCP host.
OAuth 2.1 (/mcp/oauth)
Set ETHORA_MCP_AUTH_ISSUER to the public URL of the Ethora API that hosts the authorization server (the monoserver deploy sets it). The MCP server then:
- serves RFC 9728 protected-resource metadata at
/.well-known/oauth-protected-resourceand/.well-known/oauth-protected-resource/mcp/oauth, naming the authorization server and the three scopes; - answers unauthenticated requests on
/mcp/oauthwith401andWWW-Authenticate: Bearer resource_metadata="...", which is how clients discover the flow; - validates each token against the API once per session (cached five minutes) and enforces the token's
scopeper tool: read-only tools needread; deleting, revoking and rotating (and revealing a credential) needadmin; everything else, including updates that overwrite fields and are therefore marked destructive, needswrite.search,fetch,ethora-help,ethora-statusandethora-doctorneed no scope. Tokens without a scope claim (API keys) get full access; - hides the identity tools (
ethora-user-login,ethora-user-register,ethora-session-configure,ethora-auth-mode-set,ethora-auth-mode-set,ethora-api-key-create,ethora-api-key-list,ethora-api-key-revoke) because the token already fixes who you are.
The authorization server itself is part of the Ethora backend: <issuer>/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize (a consent page with sign-in, account creation and Google sign-in), /oauth/token, /oauth/revoke and /oauth/userinfo. Users see and disconnect OAuth grants under Account, AI Assistants, Connected AI apps. When ETHORA_MCP_AUTH_ISSUER is unset, both OAuth routes return 404 and discovery omits them.
Identity scopes. Some directories (ChatGPT) require the minimal OpenID Connect surface on top of OAuth 2.1: the openid and email scopes and a userinfo endpoint that returns sub, email and email_verified. These scopes grant no access to apps or data; they only let the client see who signed in, and the consent page says so in plain words. There are no ID tokens or JWKS, because nothing consumes them.
Email confirmation is optional. Ethora never blocks sign-up or the dashboard on a confirmed address. When a client asks for the identity scopes and the account's address is not yet confirmed, the consent page adds one step: send the confirmation link, continue after confirming, or continue without sharing the address (the identity scopes are dropped from the grant and everything else proceeds). Google sign-ins arrive confirmed and skip the step. The same confirmation can be sent from Account, AI Assistants in the web app.
What agents can do
The end-to-end journey a new user typically asks for, with the tools in order:
ethora-user-register(orethora-user-login) to get an authenticated session and an API key.ethora-app-create { displayName }thenethora-app-select { appId }to make the new app current.ethora-chat-create { title }to create a group room. The result contains the room JID${appId}_${chatId}; every room tool accepts the JID or the barechatId.ethora-agent-create { name, prompt, ... }to create an AI agent persona in that app.ethora-agent-invite { agentIdOrAddress, chatJid }to put the agent in the room. A bot instance is spawned live, no restart needed.ethora-message-send { text, roomJid, waitForReplySec: 45 }to post a message and wait for the agent's answer, returned asreplies.ethora-chat-historyreads the room afterwards.ethora-agent-activate { agentId, chatJid }to make that agent the app's default responder, thenethora-widget-snippet-getfor the<script>tag that puts the AI chat widget on a website.
ethora-help { goal } returns this and the other recipes (user-login, broadcast, sources-ingest, files-upload, bot-manage, chat-test, widget, b2b-bootstrap-ai) with the calls filled in for the current state, and ethora-recipe-run executes them.
First-minute conventions
- Every create tool answers the same way.
ethora-app-create,ethora-chat-create,ethora-agent-createreturn the raw API object pluscreated(kind,id,name, andjidoraddresswhere relevant) andnext, two to four suggested calls with arguments filled in.ethora-app-createalso returnsdashboardUrl, the app in the web dashboard. ethora-help { goal }has a recipe for each headline job:new-app,in-app-chat,multi-agent-room,widget,chat-test, plus the server-integration goals. Each returns the calls in order with arguments to copy.- Who spoke.
ethora-message-sendreplies andethora-chat-historyrows carrysenderNameandsenderKind(human,agent,app), so a multi-agent room reads as "Freud: ..., Jung: ..." rather than instance ids. - Search understands intent.
searchmaps the phrases people use ("add chat to my React app", "several agents talking to each other", "webhook when a message arrives") to the documents that answer them, anddoc:not-availablesays plainly what is not exposed over MCP and where it lives instead. Whole documents are fetchable by their bare id (doc:recipes,doc:chat-component-quickstart,doc:sdk-backend-quickstart,doc:auth-map).
Documentation inside the server
instructionsin the initialize result tell the assistant how identity works on the entry point it connected through: the open endpoint explains login and register, personal-URL and Bearer sessions are told they are already authenticated and must never ask for a password or key, OAuth sessions the same plus how to react toINSUFFICIENT_SCOPE.search { query }andfetch { id }(the ChatGPT connector convention) search an in-memory corpus: the auth map, quickstarts, recipes, a hosted getting-started guide, an API keys guide and one reference entry per tool with its inputs. They work unauthenticated.- Resources
ethora://docs/auth-map,ethora://docs/chat-component/quickstart,ethora://docs/sdk-backend/quickstart,ethora://docs/recipesand promptsethora-auth-map,ethora-vite-quickstart,ethora-nextjs-quickstart,ethora-backend-sdk-quickstart,ethora-recipes,ethora-agents-quickstart.
Tool groups
A session lists the core group only at first: 24 tools covering the whole "sign in, create an app, add rooms and messages, create and activate an agent, give it a knowledge base, get the widget" journey, one variant per operation. The other groups are registered but hidden, which keeps tools/list around 40 KB instead of 120 KB and gives assistants a short list to choose from.
Three ways to get more:
ethora-tools-enable { group }enables a group for the session (or{ group: "all" }); the server sendstools/list_changedand the client refreshes. With no arguments it returns the catalogue with counts.- Calling a hidden tool by name enables its group and runs it, so a name learned from the docs or an earlier session is never refused.
?tools=allon the endpoint URL (hosted) orETHORA_MCP_TOOLS=all(stdio) lists everything up front.
search and fetch describe hidden tools too; every tool doc names its group, and doc:tool-groups is the catalogue. Legacy and async variants carry a first line naming the preferred sibling.
| Group | What it covers | Tools |
|---|---|---|
core (listed by default) |
Sign in or register, create an app, add rooms and messages, create and activate an AI agent, give it a knowledge base, get the website widget. Always listed. | ethora-status, ethora-help, ethora-feedback-submit, ethora-tools-enable, search, fetch, ethora-user-register, ethora-user-login, ethora-api-key-create, ethora-app-create, ethora-app-list, ethora-app-select, ethora-app-update, ethora-chat-create, ethora-message-send, ethora-chat-history, ethora-agent-create, ethora-agent-list, ethora-agent-update, ethora-agent-invite, ethora-agent-activate, ethora-source-site-crawl-wait, ethora-source-doc-upload, ethora-widget-snippet-get |
keys |
List and revoke API keys, reveal an app's credentials, mint and rotate app tokens. | ethora-api-key-list, ethora-api-key-revoke, ethora-app-credentials-reveal, ethora-app-token-create, ethora-app-token-list, ethora-app-token-revoke, ethora-app-token-rotate |
session |
Diagnostics, recipes and switching the session's auth mode (app token, B2B token) for server integrations. | ethora-doctor, ethora-recipe-run, ethora-session-configure, ethora-auth-mode-set, ethora-auth-mode-set, ethora-auth-mode-set |
apps-admin |
Delete, export and import whole apps; inspect default rooms. | ethora-app-delete, ethora-app-export, ethora-app-import, ethora-app-rooms-list, ethora-app-rooms-list |
rooms |
Delete rooms, broadcast to many rooms, search messages, read message context and unread counts. | ethora-chat-delete, ethora-broadcast-send, ethora-broadcast-job-get, ethora-broadcast-job-wait, ethora-message-search, ethora-message-context, ethora-chat-unread-counts |
agents-admin |
Inspect, clone (with or without its knowledge), delete, export and import agents; try an agent without a room; check and rebuild its knowledge index; edit its Memory and visibility. | ethora-agent-get, ethora-agent-clone, ethora-agent-delete, ethora-agent-export, ethora-agent-import, ethora-agent-visibility-set, ethora-agent-soul-set, ethora-agent-soul-append, ethora-agent-try, ethora-agent-knowledge-get, ethora-agent-knowledge-rebuild |
sources |
Knowledge-base maintenance: async crawl and reindex jobs, stop a crawl, list and tag sites and documents, delete URLs and documents. | ethora-source-site-crawl, ethora-source-site-crawl-cancel, ethora-source-site-reindex, ethora-source-site-reindex-wait, ethora-source-site-list, ethora-source-site-watch-list, ethora-source-site-watch-update, ethora-source-site-refresh, ethora-source-site-tags-update, ethora-source-site-url-delete, ethora-source-site-url-delete-batch, ethora-source-doc-list, ethora-source-doc-tags-update, ethora-source-doc-delete |
widget |
Read and change the website widget's saved look (colours, fonts, size, launcher, teaser, texts); live embeds pick it up without a new snippet. | ethora-widget-appearance-get, ethora-widget-appearance-set |
users-files |
Batch-create users and upload, fetch or delete files. | ethora-user-batch-create, ethora-user-batch-job-get, ethora-user-batch-job-wait, ethora-file-upload, ethora-file-get, ethora-file-delete |
legacy-bot |
The per-app bot of apps created in the dashboard before the agents framework, and the pre-v2 document tools. Prefer the agents and sources tools for anything new. | ethora-bot-get, ethora-bot-update, ethora-bot-enable, ethora-bot-disable, ethora-bot-widget-get, ethora-bot-history, ethora-bot-message-send, ethora-bot-instance-list, ethora-bot-instance-status-set, ethora-bot-instance-diagnose, ethora-bot-instance-leave, ethora-bot-instance-test, ethora-bot-enable-b2b, ethora-source-doc-upload-legacy, ethora-source-doc-delete-legacy |
b2b |
Server-to-server provisioning with a B2B token, plus code and config generators for integrations. | ethora-b2b-app-create, ethora-b2b-app-provision, ethora-b2b-app-bootstrap-ai, ethora-b2b-runbook-generate, ethora-env-examples-generate, ethora-chat-component-app-generate, ethora.b2b.auth.use, ethora.b2b.app.create, ethora.b2b.bot.enable, ethora.b2b.broadcast.wait, ethora.b2b.app.bootstrap-ai |
wallet |
Wallet balance and ERC-20 transfer. Local (stdio) only; never offered on the hosted server. | ethora-wallet-balance-get, ethora-wallet-erc20-transfer |
App deletion and bulk-delete tools are only registered when ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true (the monoserver deploy sets it; the stdio default is off). Alias tools (ethora.b2b.*, ethora-bot-message-send, ethora-bot-history) are off by default (ETHORA_MCP_ENABLE_ALIASES=true to expose them); the canonical tools cover the same ground.
Website widget
ethora-widget-snippet-get returns the tag for the embeddable AI chat widget:
<script id="chat-content-assistant" src="https://widget.<your domain>/assistant.js"
data-app-id="<appId>" data-api-base="https://api.<your domain>" defer></script>
The widget's look (colours, fonts, size, launcher, teaser bubble, texts) is saved on the app: ethora-widget-appearance-set { appearance: { "data-primary-color": "#7c3aed" } } (the widget group), the same setting as App settings > AI Widget in the admin panel. Every embed loads it when it opens, so later changes reach live sites without a new snippet. A data-* attribute written on the tag wins over the saved value on that site.
The widget answers with the app's active bot (defaultBotInstanceId). On an app created through the API run ethora-agent-create, ethora-chat-create, ethora-agent-invite and ethora-agent-activate { agentId, chatJid } first; the tool lists these prerequisites and ethora-help { goal: "widget" } walks through them. Activation runs in user auth by setting the app's default bot instance (what the admin AI Widget dropdown does). Until a bot is active, the widget's session endpoint answers AI_BOT_NOT_CONFIGURED. ethora-chat-component-app-generate produces a React App.tsx for @ethora/chat-component instead.
Configuration
Env vars (stdio and hosted)
| Variable | Meaning |
|---|---|
ETHORA_API_URL |
Full API URL, e.g. https://api.chat.ethora.com/v1 (default). On a hosted server it is fixed for all sessions |
ETHORA_BASE_URL |
Host-only alternative to ETHORA_API_URL; /v1 is appended |
ETHORA_APP_JWT |
App JWT used only by login and register (ETHORA_APP_TOKEN is a legacy alias) |
ETHORA_APP_DOMAIN_NAME |
Base app domainName; when ETHORA_APP_JWT is empty the server fetches the app JWT from GET /v1/apps/get-config?domainName=... at startup |
ETHORA_B2B_TOKEN |
B2B server token for x-custom-token tenant-actor routes |
ETHORA_MCP_TOOLS |
all lists every tool from the start instead of the core group (stdio; hosted uses ?tools=all on the URL) |
ETHORA_MCP_ENABLE_DANGEROUS_TOOLS |
true registers app deletion, wallet transfer and bulk-delete tools (default off) |
ETHORA_MCP_OPENAI_APPS_CHALLENGE |
Hosted only. Token issued by the OpenAI apps portal for domain verification; served verbatim at /.well-known/openai-apps-challenge (404 when unset) |
ETHORA_MCP_ENABLE_ALIASES |
true exposes the dot-namespaced alias tools (default off) |
Ethora MCP questions
How do I add Ethora MCP to Claude Code?
Run claude mcp add --env 'ETHORA_APP_JWT=<YOUR_ETHORA_APP_JWT>' --env 'ETHORA_B2B_TOKEN=<YOUR_ETHORA_B2B_TOKEN>' ethora-mcp-cli -- npx -y @ethora/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Ethora MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Ethora MCP provide?
It exposes 76 tools, including ethora-configure, ethora-status, ethora-help, ethora-run-recipe, ethora-doctor.
What can an AI agent do with this server?
Agents can create Ethora apps, chat rooms, and users, deploy AI agent personas, post messages, and index RAG sources.
How do I authenticate without a browser?
You can use a personal connector URL containing an API key or provide an Authorization Bearer header with your API key.