# ethora-mcp-cli [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/dappros/ethora-mcp-cli  
**GitHub Stars:** 6  
**npm Downloads (last month):** 1597  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ethora-mcp-cli

## Description
MCP server for the Ethora chat & messaging platform: chat ops, AI bots, RAG, ERC-20 wallet.

## Tools
Capabilities this server exposes over MCP:

- **ethora-status** — Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present (booleans like `hasAppJwt` — values never echoed), the selected appId/agentId, and `hosted`/`sessionId` on the hosted (Streamable HTTP) server.
Auth: none required. Errors: effectively none. Related: `ethora-doctor` for an active connectivity check.
- **ethora-help** — Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends next tool calls + recipes based on current session state.
Auth: none required — inspects state, no API calls. Errors: effectively none. Related: pass a recommended recipe id to `ethora-recipe-run`.
- **ethora-app-select** — Set the current app context for this session so app-scoped tools can omit their `appId` argument. Stores `currentAppId` and, if given, `appToken` (which defaults the auth mode to app-token unless `authMode` overrides).
Auth: none required to set the context. Errors: effectively none — a non-existent `appId` is not validated here; the first app-scoped API call surfaces the 404. Related: pairs with `ethora-auth-mode-set`.
- **ethora-source-site-crawl-wait** — Crawl a website URL and wait for the crawl to finish: enqueues the job, then polls it until it reports `completed` or `failed`. Returns `{ done, status, jobId, polls, durationMs, result }`; `done: false` with a `note` means the budget ran out while the job was still running (it usually finishes server-side anyway).
Requires: a selected app (`ethora-app-select`) or an explicit `appId`.
Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 400 malformed `url`; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side — check with `ethora-source-site-list`).
- **ethora-source-doc-upload** — Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-source-doc-upload-legacy`). Async — content becomes queryable once indexing finishes; files passed as base64, 50MB max each.
Requires: a selected app (`ethora-app-select`) or an explicit `appId`.
Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; 413 too large; 422 unsupported document type. Related: `ethora-source-doc-list`, `ethora-source-doc-delete`.
- **ethora-user-login** — Authenticate as an existing Ethora user with email + password. Stores the user session token in this MCP session and unlocks user-auth tools (`ethora-app-list`, `ethora-files-*`, `ethora-wallet-*`).
Auth: user-auth mode (`ethora-auth-mode-set` first) and a configured `appJwt`. Errors: 401/403 bad credentials; 404 email not registered; 429 per-IP rate limit — retry with backoff.
- **ethora-user-register** — Create a new Ethora user account by email + first/last name, then log in and bind the session. A password is generated when omitted and returned once. By default also mints a long-lived API key so an agent can reconnect later with `Authorization: Bearer <key>` (no human step needed).
Auth: user-auth mode and a configured `appJwt` (on a hosted server this is preset). Errors: 401 no `appJwt`; 422 email already registered or password shorter than 6 chars; 429 rate limited. Related: bulk provisioning uses `ethora-user-batch-create`.
- **ethora-api-key-create** — Mint a long-lived, revocable API key for the currently logged-in user. The key is a user token: send it as `Authorization: Bearer <key>` to the hosted MCP endpoint (or set it in the stdio client) to skip `ethora-user-login`. Shown once.
Auth: user auth (logged in). Errors: 401 not logged in; 404 on backends without API key support.
- **ethora-feedback-submit** — Send feedback about Ethora to the Ethora team: something that does not work, behaves differently from what the tool description promised, is missing, or is badly documented. It reaches the team directly, so prefer it over guessing or silently giving up when a tool fails. Recent failures in this session (tool, error code, request id) are attached automatically when `includeRecentErrors` is true, which is what makes a report from here more useful than a web form: the team can join it to the server-side log. Works whether or not you are signed in, so a problem that blocks sign-up can still be reported. Do not put credentials, API keys or end-user personal data in `message`; credential-shaped values in the attached context are redacted before sending.
Requires: nothing.
Auth: none. Works anonymously; when the session is authenticated the report is attributed to that account. Errors: 422 if `message` is shorter than 5 characters or looks like spam; 429 if too many reports were sent from this address.
- **ethora-widget-snippet-get** — Generate the <script> tag that embeds the Ethora AI chat widget (the floating launcher + chat panel that website visitors use) for an app, plus the prerequisites that must hold before it answers. No API call; pure generator using this deployment's hosted widget URL and public API base. The widget answers with the app's ACTIVE bot: for API-created apps run `ethora-agent-create` -> `ethora-agent-invite` -> `ethora-agent-activate { agentId, chatJid }` first, otherwise `POST /v2/widget/sessions` returns 422 and the widget stays silent.
Requires: an activated agent on the app (`ethora-agent-activate`); without it the widget opens but never answers.
Auth: none required (uses the selected app when `appId` is omitted). Errors: effectively none; when no hosted widget is configured the snippet carries a `<WIDGET_URL>` placeholder. Related: `ethora-agent-activate`, `ethora-bot-widget-get` (legacy per-app bot only).
- **ethora-app-list** — List all Ethora apps (tenants) owned by the currently logged-in user. Returns an array with `appId` (24-char hex), `displayName`, `domainName`, ownership and bot-status metadata. Credential fields (appSecret, tenantSecret, appToken, passwords) are redacted in the result; call `ethora-app-credentials-reveal { appId, confirm: true }` to reveal an app's appToken.
Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; empty list if the user owns no apps. Related: feed `appId` into `ethora-app-update` / `ethora-app-select`.
- **ethora-app-create** — Create a new Ethora app (tenant) owned by the currently logged-in user. Allocates a fresh 24-char hex `appId` and sets the caller as owner; counts against the owner's plan limit. Returns the new app object including `appId`. The returned app has its credential fields redacted; call `ethora-app-credentials-reveal { appId, confirm: true }` when a snippet needs the appToken.
Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; 402/403 plan limit reached; 422 invalid `displayName`. Related: server-side provisioning uses `ethora-b2b-app-create`.
- **ethora-app-update** — Update mutable fields on an app the caller owns (displayName, domainName, appTagline, primaryColor, botStatus). Partial update — omitted fields are left unchanged.
Requires: an `appId` from `ethora-app-list` or `ethora-app-create`.
Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 validation (e.g. `domainName` taken, `primaryColor` not `#RRGGBB`).
- **ethora-chat-create** — Create a new chat room (MUC room) inside an app the caller owns. Every room created this way is listed in the app's rooms (`defaultRooms`); `pinned: true` additionally makes new users auto-join it (existing users are not added), `pinned: false` (default) keeps it opt-in. Returns the new room object including its JID.
Requires: a selected app (`ethora-app-select`) or an explicit `appId`.
Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 invalid `title`.
- **ethora-agent-list** — List the reusable saved agents of an app (`GET /v2/apps/:appId/agents`, or `GET /v2/agents` for the token's own app) — a saved agent is a reusable bot definition. Returns an array of agents with ids, names, and config.
Auth: app-token mode (after `ethora-app-select` + `ethora-auth-mode-set`). Errors: 401/403 not in app-token mode or invalid appToken; empty list if the app has no saved agents.
- **ethora-agent-create** — Create a reusable AI agent (POST /v2/apps/:appId/agents). Works in user auth mode (the normal hosted mode) or B2B mode; app-token mode is not accepted by the backend. Each agent is a persona — name, avatar, system prompt, LLM config, plus response-gate settings (responseMode, cooldownSec) that control when it speaks in a room. For multi-agent scenarios (two or more personas conversing in one chat) create each one separately, then `ethora-agent-invite` them into the same room. See the `ethora-agents-quickstart` prompt for the end-to-end recipe.
Requires: a selected app (`ethora-app-select`) or an explicit `appId`; the agent is owned by that app.
- **ethora-agent-update** — Update a saved AI agent (PUT /v2/agents/:agentId). All fields are optional — only what you pass is updated. Common uses: tune the system `prompt` after a test run, switch `responseMode` to control turn-taking in multi-agent rooms, or adjust `cooldownSec`. See `ethora-agents-quickstart` prompt for the end-to-end recipe.
Requires: an agent id or address from `ethora-agent-list` or `ethora-agent-create`.
- **ethora-agent-activate** — Make an agent the app's ACTIVE widget bot: sets `App.defaultBotInstanceId` (and `botStatus: on`), which is what `POST /v2/widget/sessions` uses to decide who answers website visitors. Required before an embedded widget can answer on an API-created app. Preconditions: the agent was invited into a room of this app with `ethora-agent-invite` (that creates its bot instance). Works in user auth (app update route); falls back to the app-token `/v2/agents/:id/activate` route when an appToken is stored.
Requires: an agent already invited into a room of the selected app (`ethora-agent-create` -> `ethora-chat-create` -> `ethora-agent-invite`); the invite creates the bot instance this tool binds as the app's default responder.
Auth: user session (owner of the app). Errors: 404 no bot instance for this agent in the app (invite first); 403 not the app owner. Related: `ethora-widget-snippet-get` next, `ethora-bot-instance-list` to inspect.
- **ethora-agent-invite** — Invite an Agent into a chat room. Multiple agents can coexist in the same room — call this tool once per agent and they will all appear as members able to converse. Lazily creates a per-App BotInstance (an Ethora user with isBot:true) if one does not already exist for (agent, app). Spawns the XMPP client live; no ai-service restart required. For the full multi-agent recipe see the `ethora-agents-quickstart` prompt.
Requires: an agent (`ethora-agent-create`) and a room (`ethora-chat-create`) in the selected app.
- **ethora-message-send** — Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). The message is attributed to the app's broadcast sender (override the shown name with `senderName`). Use it to seed or test a conversation, e.g. right after `ethora-agent-invite`, and set `waitForReplySec` (up to 60) to wait for an AI agent's answer; replies are returned in `replies`. Identify the room by `roomJid` (`${appId}_${chatId}`, exactly what `ethora-chat-create` returns as `jid`) or by the bare `chatId` plus the selected app.
Requires: a room in the selected app (`ethora-chat-create`); for `replies`, an agent invited into it (`ethora-agent-invite`).
Auth: user auth (the default on the hosted server) or B2B; app-token mode is not accepted by this route. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 422 empty text. Reply detection needs the message archive (MAM) on the deployment; when it is unavailable `replies` is null and `historyUnavailable` is true.
- **ethora-chat-history** — Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). Returns `results` with `from`, `nick`, `body`, `ts` (ms) plus a `nextBefore` cursor for older pages. Identify the room by `roomJid` (`${appId}_${chatId}`) or bare `chatId` plus the selected app.
Requires: a room in the selected app (`ethora-chat-create`).
Auth: user auth (default on the hosted server) or B2B; app-token mode is not accepted. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 502 MAM_READ_FAILED or `mamUnavailable: true` when the deployment has no message archive.
- **ethora-tools-enable** — Only the core tools are listed by default. Call this to enable another group for this session; the tool list refreshes automatically (tools/list_changed). Without `group` it returns the catalogue: each group's summary, tool count and whether it is enabled. Groups: keys, session, apps-admin, rooms, agents-admin, sources, users-files, legacy-bot, b2b, wallet; `all` enables everything. Hidden tools are still described by `search` / `fetch`, and each doc names its group.
Auth: none. Errors: UNKNOWN_GROUP for a name outside the list.
- **search** — Search the Ethora documentation and tool reference: auth model (app JWT vs app token vs B2B token vs API keys), hosted-server getting started, chat-component and backend SDK quickstarts, recipes, and a reference entry for every tool with its inputs. Use it for any "how do I ..." question about Ethora before guessing; then call `fetch` with a result id to read the full text.
Auth: none required.
- **fetch** — Fetch the full text of a documentation section or tool reference entry by the id returned from `search` (e.g. `tool:ethora-app-create`, `doc:auth-map#app-jwt`, `doc:hosted-guide`).
Auth: none required. Errors: unknown id.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ethora-mcp-cli": {
    "command": "npx",
    "args": ["-y","@ethora/mcp-server"],
    "env": {
      "ETHORA_API_URL": "",
      "ETHORA_APP_JWT": "",
      "ETHORA_B2B_TOKEN": "",
      "ETHORA_MCP_TRANSPORT": "",
      "ETHORA_MCP_AUTH_ISSUER": ""
    }
  }
}
```

**Requires environment variables:** `ETHORA_API_URL`, `ETHORA_APP_JWT`, `ETHORA_B2B_TOKEN`, `ETHORA_MCP_TRANSPORT`, `ETHORA_MCP_AUTH_ISSUER` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ethora-mcp-cli MCP server does

The ethora-mcp-cli MCP server connects AI clients and autonomous agents to the Ethora chat and messaging platform. Its tools cover the main lifecycle of an Ethora deployment: creating and updating apps, selecting an app context, creating rooms, adding AI agents, sending messages, and reading archived chat history.

It also supports user registration and login, API-key creation, app credential handling, document uploads, website crawling for RAG sources, and website widget configuration. Agents can create reusable AI personas with prompts and response-gate settings, invite them into rooms, and activate one as the app’s widget bot. Documentation tools provide searchable reference material and task-oriented guidance before an agent makes API calls.

## How it works

The server can run as a hosted or self-hosted Streamable HTTP service, or locally through the stdio package command. Hosted clients connect to an Ethora MCP URL and authenticate through OAuth, a personal API-key URL, or a bearer token. A local stdio setup uses environment variables for the Ethora API and bootstrap credentials.

Each MCP session keeps private state such as the selected app, authentication mode, and available credentials. `ethora-status` reports this state without exposing secret values, while `ethora-help` recommends next actions based on it. Tool groups are disabled by default beyond the core set; `ethora-tools-enable` can expose groups such as rooms, agents, sources, users and files, wallet, or B2B operations.

## Setup and configuration

For a local process, run the npm package with Node.js 18 or newer and configure `ETHORA_API_URL` plus `ETHORA_APP_JWT`. `ETHORA_B2B_TOKEN` is available for B2B integrations. The HTTP transport is selected with `ETHORA_MCP_TRANSPORT=http`; hosted and self-hosted deployments use this mode.

A typical first sequence is to inspect state, authenticate or register a user, and list or select an app. `ethora-user-register` can return a generated password and API key once, allowing a later connection with a bearer credential. On hosted deployments, clients can instead use the OAuth endpoint or a personal connector URL.

## Tools and capabilities

- Manage Ethora apps, rooms, users, API keys, and app credentials.
- Create, update, list, invite, and activate reusable AI agents.
- Send messages and retrieve paginated archived chat history.
- Upload RAG documents and crawl websites while waiting for indexing jobs.
- Generate an Ethora AI chat-widget script after an agent is activated.
- Inspect session state, get recommended recipes, search documentation, and fetch full reference entries.
- Submit product feedback anonymously or from an authenticated session.

## Limitations and notes

The ethora-mcp-cli MCP server does not validate an app ID when it is selected; an invalid ID fails on the first app-scoped request. Document indexing is asynchronous, and uploaded files are limited to 50 MB each. Website crawls can exceed the waiting budget even though the server-side job may continue.

Authentication support depends on the operation. App-token and B2B modes handle selected app and source workflows, while several user, room, and agent operations require user authentication or B2B access. Message reply detection and history require message archive support on the Ethora deployment. Treat personal connector URLs and API keys as secrets; keys are shown only when created.

_Full upstream README: https://allmcps.com/mcp/ethora-mcp-cli/readme_