io.github.dappros/ethora-mcp-server
NPM · @ETHORA/MCP-SERVER · 3 COMPONENTS · SCANNED SEP 20
Ethora chat platform MCP: apps, users, rooms, AI agents, chat widgets. Hosted or stdio.
Available components
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score → Why this is hard to score →
Supply Chain Security98
- No malware found by supply-chain analysis.Pass
- No known CVEs affecting this package version or its production dependencies.Pass
- No install/post-install scripts declared.Pass
- 34 of 109 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency48
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 2 days ago).Pass
- Publishes a security disclosure policy (SECURITY.md).Pass
Schema Quality & AI Usability78
- 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).Pass
- AI-judged instruction clarity (excellent).Pass
- Context-footprint check failed: tool/resource definitions use about 20512 tokens (~220/item across 93 items; 89 tools + 4 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management84
- Stability check failed: the tool surface changed between 26.5.3 and 26.9.3: 4 tool removals, 0 breaking changes, 24 additions. See how to fix → Fail
Tool Coverage97
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 90% of tool parameters carry a description.Partial
Tool Safety100
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- All 10 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.Pass
- An AI judge read all 91 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
How do I install the io.github.dappros/ethora-mcp-server server?
io.github.dappros/ethora-mcp-server runs locally as an npm package, launched with npx -y @ethora/mcp-server. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.
npm · @ethora/mcp-server
claude mcp add dappros-ethora-mcp-server -- npx -y @ethora/mcp-server
{
"mcpServers": {
"dappros-ethora-mcp-server": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
]
}
}
} {
"servers": {
"dappros-ethora-mcp-server": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
]
}
}
} codex mcp add dappros-ethora-mcp-server -- npx -y @ethora/mcp-server
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"dappros-ethora-mcp-server": {
"type": "local",
"command": [
"npx",
"-y",
"@ethora/mcp-server"
],
"enabled": true
}
}
} openclaw mcp add dappros-ethora-mcp-server --command npx --arg -y --arg @ethora/mcp-server
mcp_servers:
dappros-ethora-mcp-server:
command: "npx"
args: ["-y", "@ethora/mcp-server"] {
"McpServers": {
"dappros-ethora-mcp-server": {
"Transport": "stdio",
"Command": "npx",
"Arguments": [
"-y",
"@ethora/mcp-server"
]
}
}
} assistant mcp add dappros-ethora-mcp-server -t stdio -c npx -a -y @ethora/mcp-server
{
"mcpServers": {
"dappros-ethora-mcp-server": {
"command": "npx",
"args": [
"-y",
"@ethora/mcp-server"
]
}
}
} Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 20 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 81 to 84.
- 19 Sept 26 +11
- Known CVEs: unverified → pass ▲ security
- Dependency health: unverified → 0.86 ▲ functional
- 17 Sept 26 +5
- Known CVEs: pass → unverified ▼ security
- Stability: fail → unverified ▼ security
- Tool safety: pass → unverified ▼ security
- Malware scan: unverified → pass ▲ security
- Schema quality: 191 → 220 ▼ functional
- Dependency health: 0.86 → unverified ▼ functional
- Capabilities: pass → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- Schema quality: 100 → unverified ▼ functional
- Package version: 26.9.1 → 26.9.3 functional
- Package version: 26.9.1 → 26.9.2 functional
- 16 Sept 26 −3
No change was recorded against any check on this day. Stability & Change Management went from 94 to 71.
- 15 Sept 26 +1
- Malware scan: unverified → pass ▲ security
- Schema quality: 15297 → 17412 ▼ functional
- Security disclosure: fail → pass ▲ functional
- Destructive annotations: All 10 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation. functional
- Package version: 26.9.0 → 26.9.1 functional
- 14 Sept 26 −16
- Tool safety: pass → unverified ▼ security
- Malware scan: pass → unverified ▼ security
- Stability: 0.93 → unverified ▼ security
- Stability: 0.93 → fail ▼ security
- Tool coverage: 100% → 88% ▼ functional
- Schema quality: 100 → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- Capabilities: pass → unverified ▼ functional
- Destructive annotations: 8 of 10 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "ethora-bot-instance-test-message" implies "send" and declares no destructiveHint at all, which the MCP spec reads as destructive by default. functional
- Licence: ISC → MIT functional
- Package version: 26.5.3 → 26.9.0 functional
- 13 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 90 to 93. That category is still filling its 30-day observation window: 27 days of observed history at the previous scan, 28 at this one. The score rises as the window fills, whether or not the server changes.
- 12 Sept 26 0
- Security disclosure: unverified → fail ▼ functional
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 20 Sept 2026 · Analysed npm/@ethora/mcp-server@26.9.3
Provenance No attestation
The registry publishes no build provenance for this version, so there is nothing to verify.
| Result | No attestation |
|---|---|
| Ecosystem | npm |
Background: How many MCP packages publish verified provenance →
Dependencies 109 packages
| Packages resolved | 109 |
|---|---|
| Stale | 34 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
ethora-agent-invite-to-chat Invite Agent to Chat ~277
Invite an Agent into a chat room. Multiple agents can coexist in the same room — call this tool once per agent and they will all appear as members able to converse. Lazily creates a per-App BotInstance (an Ethora user with isBot:true) if one does not already exist for (agent, app). Spawns the XMPP client live; no ai-service restart required. For the full multi-agent recipe see the `ethora-agents-quickstart` prompt. Requires: an agent (`ethora-agents-create-v2`) and a room (`ethora-app-create-chat`) in the selected app.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | Either Mongo _id (24 hex chars) or EOA-style address. |
| appId | string | – | Required in B2B mode unless already selected via ethora-app-select. |
| chatId | string | – | Mongo Chat _id (preferred when invoking from admin). |
| chatJid | string | – | Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), exactly the `jid` returned by `ethora-app-create-chat`. Preferred over `chatId`. |
No output schema declared.
No examples provided.
ethora-agent-set-visibility Set Agent Visibility ~109
Set an Agent's visibility (private | unlisted | public). Public agents can be invited cross-app by anyone who knows the address. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| visibility | string | yes | – |
No output schema declared.
No examples provided.
ethora-agent-soul-append Append to Agent Prompt ~122
Append a fragment to an Agent's SOUL.MD (its evolving identity / private notes). Operator-driven; the Agent itself can also self-edit via the same endpoint when called by ai-service. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| append | string | yes | – |
No output schema declared.
No examples provided.
ethora-agent-soul-set Set Agent Prompt ~116
Replace an Agent's SOUL.MD with the provided markdown. Operator-driven; alternative to -append. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| soulMd | string | yes | Replace SOUL.MD contents. Pass empty string to clear. |
No output schema declared.
No examples provided.
ethora-agents-activate-v2 Activate Agent for Widget ~397
Make an agent the app's ACTIVE widget bot: sets `App.defaultBotInstanceId` (and `botStatus: on`), which is what `POST /v2/widget/sessions` uses to decide who answers website visitors. Required before an embedded widget can answer on an API-created app. Preconditions: the agent was invited into a room of this app with `ethora-agent-invite-to-chat` (that creates its bot instance). Works in user auth (app update route); falls back to the app-token `/v2/agents/:id/activate` route when an appToken is stored. Requires: an agent already invited into a room of the selected app (`ethora-agents-create-v2` -> `ethora-app-create-chat` -> `ethora-agent-invite-to-chat`); the invite creates the bot instance this tool binds as the app's default responder. Auth: user session (owner of the app). Errors: 404 no bot instance for this agent in the app (invite first); 403 not the app owner. Related: `ethora-widget-embed-snippet` next, `ethora-bot-instances-list` to inspect.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Id (or address) of the agent to activate. Get it from `ethora-agents-list-v2` / `ethora-agents-create-v2`. |
| agentIdOrAddress | string | – | Alias for `agentId` - either name is accepted, pass whichever you have. |
| appId | string | – | App to activate the agent for. Defaults to the app from `ethora-app-select`. |
| chatJid | string | – | Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat… |
No output schema declared.
No examples provided.
ethora-agents-clone-v2 Clone Agent ~264
Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (`POST /v2/agents/:agentId/clone`). The source agent is unchanged; the new clone becomes the session's current agent context. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 404 source `agentId` not found; 422 overridden `slug` collides.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Id of the source agent to clone. Get it from `ethora-agents-list-v2`. |
| agentIdOrAddress | string | – | Alias for `agentId` - either name is accepted, pass whichever you have. |
| name | string | – | Name for the clone. Omit to inherit the source agent's name. |
| slug | string | – | URL-safe unique slug for the clone. Omit to let the server derive one; must not collide with an existing agent. |
| summary | string | – | Summary for the clone. Omit to inherit the source agent's summary. |
No output schema declared.
No examples provided.
ethora-agents-create-v2 Create Agent ~911
Create a reusable AI agent (POST /v2/apps/:appId/agents). Works in user auth mode (the normal hosted mode) or B2B mode; app-token mode is not accepted by the backend. Each agent is a persona — name, avatar, system prompt, LLM config, plus response-gate settings (responseMode, cooldownSec) that control when it speaks in a room. For multi-agent scenarios (two or more personas conversing in one chat) create each one separately, then `ethora-agent-invite-to-chat` them into the same room. See the `ethora-agents-quickstart` prompt for the end-to-end recipe. Requires: a selected app (`ethora-app-select`) or an explicit `appId`; the agent is owned by that app.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather tha… |
| botAvatarUrl | string | – | URL of the avatar image shown next to bot messages. |
| botDisplayName | string | – | Display name used inside the chat UI. Defaults to `name`. |
| categories | array | – | Free-form category tags for agent directory listings. |
| cooldownSec | integer | – | Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking in multi-agent scenarios. |
| flowsYaml | string | – | Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn… |
| greetingMessage | string | – | Optional message the agent posts when it first joins a room. |
| isPublished | boolean | – | Convenience alias for setting visibility='public'. |
| isRAG | boolean | – | Enable retrieval-augmented generation from indexed sources. |
| llmModel | string | – | LLM model override (e.g. 'gpt-4o-mini'). |
| llmProvider | string | – | LLM provider override (e.g. 'openai'). Defaults to the app's configured provider. |
| name | string | – | Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching. |
| prompt | string | – | System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how tu… |
| ragTags | array | – | Optional RAG tag filter — restrict retrieval to sources matching these tags. |
| responseMode | string | – | When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate de… |
| responseProbability | number | – | If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages. |
| slug | string | – | URL-safe slug (auto-generated from name if omitted). |
| summary | string | – | Short bio shown in agent lists. |
| trigger | string | – | Legacy trigger field. Prefer the newer `responseMode` for new agents. |
| visibility | string | – | 'private' (only invitable inside the owning app) or 'public' (cross-app invitable). |
No output schema declared.
No examples provided.
ethora-agents-export-v2 Export Agent ~145
Export an Agent as a portable bundle (GET /v2/agents/:idOrAddress/export). format=json returns the bundle object directly; feed it back to `ethora-agents-import-v2` to recreate the Agent in another App/tenant. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| format | string | – | Defaults to json. Prefer json for MCP round-trips. |
No output schema declared.
No examples provided.
ethora-agents-get-v2 Get Agent ~201
Fetch one reusable saved agent's full config by id (`GET /v2/agents/:agentId`) — prompt, LLM, RAG settings, visibility. Also sets this agent as the session's current agent context (no server-side change). Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 404 `agentId` not an agent of the current app. Related: get ids from `ethora-agents-list-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Id of the saved agent to fetch. Get it from `ethora-agents-list-v2`. |
| agentIdOrAddress | string | – | Alias for `agentId` - either name is accepted, pass whichever you have. |
No output schema declared.
No examples provided.
ethora-agents-import-v2 Import Agent ~129
Import an Agent from a bundle produced by `ethora-agents-export-v2` (POST /v2/agents/import, application/json body IS the bundle). Optionally scope the new Agent to an owning App via ownerAppId. Requires: a bundle produced by `ethora-agents-export-v2` with format json.
| Name | Type | Req | Description |
|---|---|---|---|
| bundle | object | yes | The bundle object returned by `ethora-agents-export-v2` with format=json. Pass it through unchanged. |
| ownerAppId | string | – | Owning App for the imported Agent (defaults server-side). |
No output schema declared.
No examples provided.
ethora-agents-list-v2 List Agents ~173
List the reusable saved agents of an app (`GET /v2/apps/:appId/agents`, or `GET /v2/agents` for the token's own app) — a saved agent is a reusable bot definition. Returns an array of agents with ids, names, and config. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 not in app-token mode or invalid appToken; empty list if the app has no saved agents.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId whose agents to list (`GET /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`; without either, lists the agents of the token's own app. |
No output schema declared.
No examples provided.
ethora-agents-update-v2 Update Agent ~709
Update a saved AI agent (PUT /v2/agents/:agentId). All fields are optional — only what you pass is updated. Common uses: tune the system `prompt` after a test run, switch `responseMode` to control turn-taking in multi-agent rooms, or adjust `cooldownSec`. See `ethora-agents-quickstart` prompt for the end-to-end recipe. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Mongo _id (24 hex chars) of the agent to update. |
| agentIdOrAddress | string | – | Alias for `agentId` - either name is accepted, pass whichever you have. |
| botAvatarUrl | string | – | Avatar image URL. |
| botDisplayName | string | – | Display name in chat UI. |
| categories | array | – | Category tags for directory listings. |
| cooldownSec | integer | – | Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking. |
| flowsYaml | string | – | Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn… |
| greetingMessage | string | – | Message the agent posts when it first joins a new room. |
| isPublished | boolean | – | Convenience alias for visibility='public'. |
| isRAG | boolean | – | Enable RAG retrieval. |
| llmModel | string | – | LLM model override. |
| llmProvider | string | – | LLM provider override. |
| name | string | – | New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary. |
| prompt | string | – | Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response g… |
| ragTags | array | – | RAG tag filter. |
| responseMode | string | – | When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbabi… |
| responseProbability | number | – | If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot. |
| slug | string | – | URL-safe slug. |
| summary | string | – | Short bio. |
| trigger | string | – | Legacy trigger field. Prefer `responseMode`. |
| visibility | string | – | 'private' or 'public' (cross-app invitable). |
No output schema declared.
No examples provided.
ethora-api-key-create Create API Key ~143
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.
| Name | Type | Req | Description |
|---|---|---|---|
| name | string | – | Label to recognise the key later (e.g. `ci-runner`, `claude-desktop`). |
| ttlDays | integer | – | Lifetime in days. Server default applies when omitted. |
No output schema declared.
No examples provided.
ethora-api-key-list List API Keys ~39
List the current user's API keys (id, name, createdAt, expiresAt). Token values are never returned. Auth: user auth.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-api-key-revoke Revoke API Key ~92
Revoke one of the current user's API keys by id. Clients using that key stop working immediately. Requires: a key id from `ethora-api-key-list` or `ethora-api-key-create`. Auth: user auth. Errors: 404 unknown id.
| Name | Type | Req | Description |
|---|---|---|---|
| id | string | yes | API key id as returned by `ethora-api-key-create` / `ethora-api-key-list`. |
No output schema declared.
No examples provided.
ethora-app-create Create App ~184
Create a new Ethora app (tenant) owned by the currently logged-in user. Allocates a fresh 24-char hex `appId` and sets the caller as owner; counts against the owner's plan limit. Returns the new app object including `appId`. The returned app has its credential fields redacted; call `ethora-app-credentials { appId, confirm: true }` when a snippet needs the appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; 402/403 plan limit reached; 422 invalid `displayName`. Related: server-side provisioning uses `ethora-b2b-app-create`.
| Name | Type | Req | Description |
|---|---|---|---|
| displayName | string | yes | Human-readable app name shown to users in the app picker and on the public landing page. Not required to be unique across accounts. |
No output schema declared.
No examples provided.
ethora-app-create-chat Create Chat Room ~264
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`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex ObjectId of the app to create the chat room in. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| pinned | boolean | – | If `true`, the room is added to the app's default rooms list — every new user of the app auto-joins it. If `false`, the room exists but users must be added explicitly. |
| title | string | yes | Display name for the new chat room. Visible to all members; not required to be unique within the app. |
No output schema declared.
No examples provided.
ethora-app-credentials Reveal App Token ~233
Reveal the appToken of an app the caller owns, for a chat-component snippet or a widget config. Every other tool redacts appToken, appSecret and tenantSecret from its results because tool output enters the model's context and client logs; this tool returns exactly { appId, appToken, note } and nothing else. The App Secret is never returned over MCP: it is shown only in the web dashboard (app settings, API tab), and backend integrations should use revocable server tokens from that tab instead of the secret. Requires: an app you own (`ethora-app-create` or `ethora-app-list`) and `confirm: true`. Auth: user auth (app owner). Errors: 401 not logged in; 403 not the owner; 404 unknown `appId`; validation error unless `confirm` is `true`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex app id. Defaults to the app selected with `ethora-app-select`. |
| confirm | boolean | yes | Must be `true`: acknowledges that the token is a credential and will appear in this conversation. |
No output schema declared.
No examples provided.
ethora-app-delete-chat Delete Chat Room ~217
Permanently delete a chat room from an app the caller owns — removes the MUC room, its message archive, and all member affiliations. Irreversible; gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true. Requires: a room from `ethora-app-get-default-rooms` or `ethora-app-create-chat`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 `chatJid` not a room in the app.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex ObjectId of the app the chat room belongs to. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| chatJid | string | yes | Room JID (XMPP address) of the chat to delete, e.g. `<roomId>@conference.<host>`. Obtain from `ethora-app-get-default-rooms` or the response of `ethora-app-create-chat`. |
No output schema declared.
No examples provided.
ethora-app-export-v2 Export App ~146
Export an App as a portable bundle (GET /v2/apps/:appId/export). format=json returns the bundle object directly. Use `include` to select sections (e.g. 'chats,users,sources,botInstances'). Feed the result to `ethora-app-import-v2`. Requires: a selected app (`ethora-app-select`) or an explicit `appId`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | Required in B2B mode unless already selected via ethora-app-select. |
| format | string | – | – |
| include | string | – | Comma-separated sections to include, e.g. 'chats,users,sources,botInstances'. |
No output schema declared.
No examples provided.
ethora-app-get-default-rooms Get Default Rooms ~106
List the default chat rooms (MUC rooms) of the currently selected Ethora app — every new user auto-joins these. Returns rooms with their JIDs and titles. Auth: user-auth mode, active session; operates against the app set via `ethora-app-select`. Errors: 400 no app currently selected; 401 not logged in. Related: `ethora-app-get-default-rooms-with-app-id` to pass `appId` explicitly.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-app-get-default-rooms-with-app-id Get Default Rooms for App ~163
List the default chat rooms of a specific Ethora app, passed via `appId` (or the currently selected app). Returns rooms with their JIDs and titles. Requires: an `appId` from `ethora-app-list` or `ethora-app-create`. Auth: user-auth mode, active session; the caller needs read access (ownership or room membership). Errors: 400 no `appId` and none selected; 401 not logged in; 403 no read access; 404 unknown `appId`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex ObjectId of the app whose default rooms you want to read. Optional — defaults to the app most recently passed to `ethora-app-select`. |
No output schema declared.
No examples provided.
ethora-app-import-v2 Import App ~107
Import an App from a bundle produced by `ethora-app-export-v2` (POST /v2/apps/import, application/json body IS the bundle). B2B / tenant-actor auth. domainNameOverride renames the imported App's domain. Requires: a bundle produced by `ethora-app-export-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| bundle | – | – | The exported bundle object (the json export output). |
| domainNameOverride | string | – | Rename the imported App's domainName. |
No output schema declared.
No examples provided.
ethora-app-list List Apps ~153
List all Ethora apps (tenants) owned by the currently logged-in user. Returns an array with `appId` (24-char hex), `displayName`, `domainName`, ownership and bot-status metadata. Credential fields (appSecret, tenantSecret, appToken, passwords) are redacted in the result; call `ethora-app-credentials { appId, confirm: true }` to reveal an app's appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; empty list if the user owns no apps. Related: feed `appId` into `ethora-app-update` / `ethora-app-select`.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-app-select Select App ~239
Set the current app context for this session so app-scoped tools can omit their `appId` argument. Stores `currentAppId` and, if given, `appToken` (which defaults the auth mode to app-token unless `authMode` overrides). Auth: none required to set the context. Errors: effectively none — a non-existent `appId` is not validated here; the first app-scoped API call surfaces the 404. Related: pairs with `ethora-auth-use-app`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | yes | 24-char hex Ethora appId to set as the current context. Get it from `ethora-app-list`, `ethora-app-create`, or a B2B create/provision response. |
| appToken | string | – | Per-app appToken to store alongside the appId. If provided, the active auth mode switches to app-token (unless `authMode` says otherwise). Secret. |
| authMode | string | – | Auth mode to keep after selecting the app. Omit to let the mode default to app-token when an `appToken` is given, or stay unchanged otherwise. |
No output schema declared.
No examples provided.
ethora-app-tokens-create-v2 Create App Token ~232
Mint a new app token for an app. The secret token value is returned exactly once and cannot be retrieved again — capture it immediately. Returns the new token including its one-time secret value and `tokenId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`. Related: manage with `ethora-app-tokens-list-v2` / `-rotate-v2` / `-revoke-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId to mint the token for. Optional — defaults to the app set via `ethora-app-select`. |
| label | string | – | Human-readable label to identify this token later (e.g. `staging`, `ci`). Shown in `ethora-app-tokens-list-v2`. |
| timeoutMs | integer | – | HTTP timeout for this request, in milliseconds. Default 10000. |
No output schema declared.
No examples provided.
ethora-app-tokens-list-v2 List App Tokens ~164
List the app tokens issued for an app — metadata only (`tokenId`, label, created/rotated timestamps, status); the secret token values are never returned (only shown once at create/rotate time). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId to list tokens for. Optional — defaults to the app set via `ethora-app-select`. |
| timeoutMs | integer | – | HTTP timeout for this request, in milliseconds. Default 10000. |
No output schema declared.
No examples provided.
ethora-app-tokens-revoke-v2 Revoke App Token ~238
Permanently revoke an app token by `tokenId` — it stops working immediately; any client, SDK, or MCP session still using it gets auth failures. No replacement is issued. Requires: a token id from `ethora-app-tokens-list-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`. Related: get `tokenId` from `ethora-app-tokens-list-v2`; `ethora-app-tokens-rotate-v2` for revoke-and-replace.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`. |
| timeoutMs | integer | – | HTTP timeout for this request, in milliseconds. Default 10000. |
| tokenId | string | yes | Id of the token to revoke. Get it from `ethora-app-tokens-list-v2`. |
No output schema declared.
No examples provided.
ethora-app-tokens-rotate-v2 Rotate App Token ~262
Rotate an app token: revoke an existing token and issue a replacement in one step. The old `tokenId` is revoked immediately — anything using it stops working at once. The new secret value is returned exactly once — capture it immediately. Requires: a token id from `ethora-app-tokens-list-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId` or `tokenId`. Related: `ethora-app-tokens-revoke-v2` to revoke without a replacement.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`. |
| label | string | – | Label for the replacement token. Omit to inherit the old token's label. |
| timeoutMs | integer | – | HTTP timeout for this request, in milliseconds. Default 10000. |
| tokenId | string | yes | Id of the token to revoke and replace. Get it from `ethora-app-tokens-list-v2`. |
No output schema declared.
No examples provided.
ethora-app-update Update App ~373
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`).
| Name | Type | Req | Description |
|---|---|---|---|
| appDescription | string | – | Deprecated alias for `appTagline`, kept so older callers keep working. Prefer `appTagline`. |
| appId | string | – | 24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| appTagline | string | – | Short tagline shown on the public app landing page. |
| botStatus | string | – | `on` enables the AI bot for new conversations (requires a configured prompt — see `ethora-bot-update-v2`); `off` disables it. Does not change the bot's configured prompt or sources. |
| displayName | string | – | New human-readable app name. Visible in the app picker and on the public landing page. |
| domainName | string | – | Subdomain to host the web app at. Setting `abcd` makes the web app available at `abcd.ethora.com`. Must be unique across all Ethora apps; lower-case alphanumerics and dashes only. |
| primaryColor | string | – | Primary brand color in hex `#RRGGBB` format (e.g. `#F54927`). Used throughout the app UI. |
No output schema declared.
No examples provided.
ethora-auth-use-app Use App Token Auth ~93
Switch this session's active auth mode to app-token, so subsequent app-scoped calls authenticate with the configured `appToken`. Auth: requires an `appToken` to already be configured (via `ethora-configure`, ETHORA_APP_TOKEN env, or `ethora-app-select`). Errors: returns an error if no `appToken` is configured. Related: use after `ethora-app-select`.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-auth-use-b2b Use B2B Auth ~135
Switch this session's active auth mode to B2B, so subsequent calls authenticate as a tenant actor via the `x-custom-token` header. Auth: requires a `b2bToken` (JWT with `type=server`) to already be configured (via `ethora-configure` or ETHORA_B2B_TOKEN env). Errors: returns an error if no `b2bToken` is configured. Related: server-side automation — pairs with `ethora-b2b-app-create`, `ethora-users-batch-create-v2`, `ethora-app-tokens-*-v2`.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-auth-use-user Use User Auth ~94
Switch this session's active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. Auth: the switch needs nothing, but user-auth tools only work once `ethora-user-login` stores a user token (login also needs a configured `appJwt`). Errors: none on the switch; downstream tools return 401 until login succeeds. Related: follow with `ethora-user-login`.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-b2b-app-bootstrap-ai Bootstrap AI App (B2B) ~496
One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. Source ingest and bot activation are best-effort (the app is still created if a later step fails); crawl/embedding continues asynchronously after this returns. Returns a per-step log including the new `appId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`); internally switches to app-token mode for source-ingest steps. Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: rooms+tokens variant is `ethora-b2b-app-provision`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentDisplayName | string | – | Phase 1: create a new Agent with this display name as part of bootstrap. |
| agentPrompt | string | – | Phase 1: persona/instructions for the newly-created Agent. |
| agentVisibility | string | – | Phase 1: visibility for the newly-created Agent. |
| botTrigger | string | – | Optional bot trigger (e.g. '/bot' or 'any_message') |
| crawlUrl | string | – | Optional website URL to crawl and index into the new app's RAG sources. |
| displayName | string | yes | Display name for the new app. |
| docs | array | – | Optional docs to ingest (base64) |
| enableBot | boolean | – | If true, enables botStatus=on (best-effort AI service activation) |
| followLink | boolean | – | For `crawlUrl`: also follow in-domain links (default true). Can ingest many pages. |
| inviteToDefaultRoom | boolean | – | Phase 1: if true (default), invite the newly-created Agent into the App's first default room. |
| llmModel | string | – | Optional generation model for the default AI bot (example: 'gpt-4o-mini'). |
| llmProvider | string | – | Optional generation provider for the default AI bot (example: 'openai' or 'openai-compatible'). |
| savedAgentId | string | – | Optional saved agent to bind as the active bot for the new app. |
| setAsCurrent | boolean | – | If true (default), set the new app as the session's current app and switch to app-token auth so follow-up tools can omit appId. |
No output schema declared.
No examples provided.
ethora-b2b-app-create Create App (B2B) ~180
Create a new Ethora app (tenant) server-side using B2B auth — the partner/integrator equivalent of `ethora-app-create`. Allocates a fresh 24-char hex `appId`; does not create tokens, rooms, or a bot. Returns the new app object including `appId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode or invalid `b2bToken`; 422 invalid `displayName`. Related: all-in-one path is `ethora-b2b-app-bootstrap-ai` / `ethora-b2b-app-provision`.
| Name | Type | Req | Description |
|---|---|---|---|
| displayName | string | yes | Human-readable app name shown to users in the app picker and on the public landing page. |
No output schema declared.
No examples provided.
ethora-b2b-app-provision Provision App (B2B) ~401
One-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. Later-step failures don't undo earlier steps. Returns a per-step log including `appId` and the created tokens (returned once — capture them). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: `ethora-b2b-app-bootstrap-ai` does sources+bot but not tokens/rooms.
| Name | Type | Req | Description |
|---|---|---|---|
| botGreetingMessage | string | – | Greeting message the bot posts when a conversation starts. |
| botPrompt | string | – | System prompt for the new app's bot. |
| botTrigger | string | – | Bot trigger: `any_message` (every message) or `/bot` (only /bot-prefixed messages). |
| displayName | string | yes | Display name for the new app. |
| enableBot | boolean | – | If true, enable the new app's bot using the first minted app token. |
| llmModel | string | – | LLM model id for the bot, e.g. `gpt-4o-mini`. Must be available for the chosen provider. |
| llmProvider | string | – | LLM provider for the bot, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend. |
| rooms | array | – | Default chat rooms to create in the new app. Up to 20. |
| savedAgentId | string | – | Optional id of an existing saved agent to bind as the new app's active bot, instead of setting prompt fields by hand. |
| tokenLabels | array | – | Labels for the app tokens to mint, one token per label. Default: ['default']. 1–5 tokens. |
No output schema declared.
No examples provided.
ethora-b2b-bot-enable Enable Legacy Bot (B2B) ~259
Enable the LEGACY per-app aiBot (B2B auth). NOTE: apps created via the API/B2B no longer auto-provision a legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED on a clean app. The forward path for B2B AI is the Agents API — use `ethora-b2b-app-bootstrap-ai` or `ethora-agents-create-v2` + `ethora-agent-invite-to-chat`. This tool remains valid for apps that already have a legacy aiBot (e.g. admin-panel apps created with a default chat). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId whose bot to enable. Optional — defaults to the app set via `ethora-app-select`. |
| botTrigger | string | – | When the bot responds: `/bot` (only messages starting with /bot) or `any_message` (every message). Omit to leave the existing trigger unchanged. |
No output schema declared.
No examples provided.
ethora-bot-disable-v2 Disable Legacy Bot ~199
Turn the AI bot off for an app (sets bot `status: "off"`) — it stops responding. The configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling restores the same behavior. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: `ethora-bot-enable-v2` to turn back on.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
No output schema declared.
No examples provided.
ethora-bot-enable-v2 Enable Legacy Bot ~237
Enable the LEGACY per-app aiBot using app-token or B2B auth. NOTE: clean API/B2B-created apps have no legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED there — use the Agents API (`ethora-agents-create-v2` + `ethora-agent-invite-to-chat`, or `ethora-b2b-app-bootstrap-ai`) for B2B AI. Valid for apps that already have a legacy aiBot. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| trigger | string | – | When the bot responds: `any_message` (every message) or `/bot` (only /bot-prefixed messages). Omit to leave the existing trigger unchanged. |
No output schema declared.
No examples provided.
ethora-bot-get-v2 Get Legacy Bot ~186
Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: change config with `ethora-bot-update-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app). |
No output schema declared.
No examples provided.
ethora-bot-instance-diag Diagnose Bot Instance ~133
Diagnose a specific BotInstance for an Agent (GET /v2/agents/:idOrAddress/bot-instances/:botInstanceId/diag). Returns live XMPP/ai-service status and recent activity for troubleshooting. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| botInstanceId | string | yes | – |
No output schema declared.
No examples provided.
ethora-bot-instance-leave-chat Remove Bot from Chat ~149
Remove a BotInstance from a chat room (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/leave-chat). The inverse of `ethora-agent-invite-to-chat`. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| botInstanceId | string | yes | – |
| chatJid | string | yes | Fully-qualified room JID to leave. |
No output schema declared.
No examples provided.
ethora-bot-instance-status Bot Instance Status ~86
Turn a specific BotInstance on or off. Off detaches it from XMPP; on re-spawns the XMPP client live. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).
| Name | Type | Req | Description |
|---|---|---|---|
| botInstanceId | string | yes | – |
| status | string | yes | – |
No output schema declared.
No examples provided.
ethora-bot-instance-test-message Send Test Message to Bot ~184
Send a test message from a BotInstance (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/test-message). Omit roomJid to fan out to every room the BotInstance is in. Requires the ai-service to be running. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have. |
| agentIdOrAddress | string | – | – |
| botInstanceId | string | yes | – |
| roomJid | string | – | Target a specific room JID; omit to broadcast to all the bot's rooms. |
| text | string | – | Message body. Optional/empty is allowed. |
No output schema declared.
No examples provided.
ethora-bot-instances-list List Bot Instances ~101
List BotInstances. Filter by appId (caller's App by default) and/or agentId. Requires: at least one invited agent in the app (`ethora-agent-invite-to-chat`); otherwise the list is empty.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | – | – |
| agentIdOrAddress | string | – | Alias for `agentId` - either name is accepted, pass whichever you have. |
| appId | string | – | – |
No output schema declared.
No examples provided.
ethora-bot-update-v2 Update Legacy Bot ~675
Configure the AI bot for an app — prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. Partial update — omitted fields are left unchanged. `status: "on"` activates the bot (best-effort; needs a prompt + LLM and a backend AI service). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; 422 validation (e.g. an `llmProvider`/`llmModel` not enabled). Related: `ethora-bot-get-v2`, `ethora-agents-activate-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| botAvatarUrl | string | – | Public URL of the bot's avatar image. |
| botDisplayName | string | – | Bot's display name shown in chat. |
| botFirstName | string | – | Bot's first name in its user profile. |
| botLastName | string | – | Bot's last name in its user profile. |
| chatId | string | – | Restrict the bot to a single chat by id. Omit to apply app-wide. |
| greetingMessage | string | – | Message the bot posts when a conversation starts. |
| isRAG | boolean | – | If true, the bot retrieves from the app's indexed RAG sources (see the `ethora-sources-*` tools) when answering. |
| llmModel | string | – | LLM model id, e.g. `gpt-4o-mini`. Must be available for the chosen `llmProvider`. |
| llmProvider | string | – | LLM provider, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend's AI service config. |
| prompt | string | – | System prompt that defines the bot's persona and behavior. |
| ragTags | array | – | Restrict RAG retrieval to sources tagged with these tags (see `ethora-sources-site-tags-update-v2` / `ethora-sources-docs-tags-update-v2`). |
| savedAgentId | string | – | Id of a saved agent whose config should back this bot. Alternative to setting prompt/LLM/RAG fields individually. |
| status | string | – | `on` activates the bot, `off` deactivates it. Omit to leave the current status unchanged. |
| trigger | string | – | When the bot responds: `any_message` (replies to every message) or `/bot` (only messages starting with /bot). |
| widgetPublicEnabled | boolean | – | If true, expose the bot through a public embeddable chat widget. |
| widgetPublicUrl | string | – | Public URL for the embeddable widget. Usually read via `ethora-bot-widget-v2` rather than set here. |
No output schema declared.
No examples provided.
ethora-bot-widget-v2 Get Legacy Bot Widget ~201
LEGACY: read the per-app bot widget config (`GET /v2/bot/widget`); only apps that already have a legacy aiBot have one, API-created apps get 422. For the embeddable AI chat widget use `ethora-widget-embed-snippet` instead — the widget config and public widget URL metadata needed to embed the bot on a website. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 not in app-token mode or invalid appToken. Related: enable/disable via `widgetPublicEnabled` in `ethora-bot-update-v2`.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-chats-broadcast-job-v2 Get Broadcast Job ~198
Fetch the current status and per-room results of a broadcast job by `jobId` (one-shot, no polling). Returns the job object with its `state` (pending/running/completed/failed). Requires: a selected app with at least one room (`ethora-app-create-chat`). Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Errors: 401/403 wrong auth; 404 unknown `jobId`. Related: `ethora-wait-broadcast-job-v2` for a blocking wait.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId the job belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| jobId | string | yes | Job id returned by `ethora-chats-broadcast-v2`. |
No output schema declared.
No examples provided.
ethora-chats-broadcast-v2 Broadcast Message ~298
Enqueue an asynchronous broadcast job posting a message to one or more chat rooms of an app — returns a `jobId`; messages are not sent synchronously. Targeting is exclusive: `allRooms`, `chatIds`, or `chatNames`, not a mix. Requires: a selected app with at least one room (`ethora-app-create-chat`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 400 no target or conflicting targets; 404 unknown `appId` or room. Related: track with `ethora-wait-broadcast-job-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| allRooms | boolean | – | If true, broadcast to every room in the app. Mutually exclusive with `chatIds` and `chatNames`. |
| appId | string | – | 24-char hex appId to broadcast in. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app). |
| chatIds | array | – | Explicit list of chat ids to target. Mutually exclusive with `allRooms` and `chatNames`. |
| chatNames | array | – | Explicit list of chat JIDs or localparts to target. Mutually exclusive with `allRooms` and `chatIds`. |
| text | string | yes | Plain-text message body to broadcast to the targeted rooms. |
No output schema declared.
No examples provided.
ethora-chats-history-v2 Get Chat History ~325
Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). Returns `results` with `from`, `nick`, `body`, `ts` (ms) plus a `nextBefore` cursor for older pages. Identify the room by `roomJid` (`${appId}_${chatId}`) or bare `chatId` plus the selected app. Requires: a room in the selected app (`ethora-app-create-chat`). Auth: user auth (default on the hosted server) or B2B; app-token mode is not accepted. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 502 MAM_READ_FAILED or `mamUnavailable: true` when the deployment has no message archive.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | – | 24-char hex appId. Optional when `roomJid` carries it or an app is selected. |
| before | integer | – | Pagination cursor: only messages older than this timestamp (ms), from a previous `nextBefore`. |
| chatId | string | – | Bare chat id. Needs an app: pass `appId` or select one with `ethora-app-select`. |
| limit | integer | – | Maximum number of most-recent messages to return (default 100). |
| roomJid | string | – | Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`). Either this or `chatId` is required. |
No output schema declared.
No examples provided.
What is the io.github.dappros/ethora-mcp-server server?
io.github.dappros/ethora-mcp-server is listed in the public MCP registry as io.github.dappros/ethora-mcp-server. Ethora chat platform MCP: apps, users, rooms, AI agents, chat widgets. Hosted or stdio. This page covers its npm package (@ethora/mcp-server).
Is the io.github.dappros/ethora-mcp-server server safe to use?
io.github.dappros/ethora-mcp-server scores 83 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 20 September 2026. It declares no install or post-install scripts. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.
What tools does the io.github.dappros/ethora-mcp-server server expose?
io.github.dappros/ethora-mcp-server exposes 89 tools: ethora-configure, ethora-status, ethora-help, ethora-run-recipe, ethora-doctor, and 84 more. Their descriptions and schemas cost roughly 20,156 tokens of context every time the server is loaded.
Is the io.github.dappros/ethora-mcp-server server still maintained?
io.github.dappros/ethora-mcp-server is still listed as active in the MCP registry. We last reached this channel on 20 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.
What licence is the io.github.dappros/ethora-mcp-server server under?
io.github.dappros/ethora-mcp-server declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.