io.github.dappros/ethora-mcp-cli

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.

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

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.

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

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

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

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

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.

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.

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

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.

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.

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

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

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

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

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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.

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.

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.

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.

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

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

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

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

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.

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.

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

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

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

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

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

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