# Ethora MCP server

> Enables AI agents to manage chat rooms, create users, deploy AI personas, and automate messaging within the Ethora platform.

- Repository: https://github.com/dappros/ethora-mcp-cli
- Page: https://hostedmcp.org/servers/dappros/ethora-mcp-cli
- Transport: stdio
- Stars: 6
- License: MIT
- Latest version: 26.5.2

## Install

### Claude Code

```sh
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
```

### Cursor (`~/.cursor/mcp.json`)

```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>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```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>"
      }
    }
  }
}
```

### VS Code CLI

```sh
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>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```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>"
      }
    }
  }
}
```

### Codex

```sh
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-server
```

### Codex config.toml (`~/.codex/config.toml`)

```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>"
```

### Gemini CLI

```sh
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-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```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>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `ETHORA_APP_JWT` | no | yes | 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. |
| `ETHORA_B2B_TOKEN` | no | yes | 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. |
| `ETHORA_API_URL` | no | no | 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` | no | no | 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` | no | no | Set to 'true' to expose destructive tools (app deletion, wallet transfers, bulk delete). Disabled by default. |

## Tools (76)

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

## FAQ

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