io.github.dappros/ethora-mcp-server
NPM · @ETHORA/MCP-SERVER · SCANNED AUG 3
MCP server for the Ethora chat & messaging platform: chat ops, AI agents, RAG, automation.
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 →
Supply Chain Security87
- No malware found by supply-chain analysis.Pass
- Only part of the dependency tree could be resolved (108 of 109), so this covers what we could see, not the whole tree.Partial
- No install/post-install scripts declared.Pass
- Only part of the dependency tree could be resolved (108 of 109), so this covers what we could see, not the whole tree. View diagnostics → Partial
Provenance & Transparency45
- 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 (ISC).Pass
- Actively maintained (last published 80 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability77
- 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 14235 tokens (~195/item across 73 items; 69 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 Management27
- Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
Add this component to your MCP client. Where a client-specific snippet is available, pick your client below and copy it straight into your config; otherwise use the connection detail shown.
npm · @ethora/mcp-server
claude mcp add dappros-ethora-mcp-server -- npx -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": {
"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.
- 3 Aug 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.
- 2 Aug 26 +30
- Provenance: unverified → fail ▼ security
- Install scripts: unverified → pass ▲ security
- Known CVEs: unverified → partial ▲ security
- License: unverified → pass ▲ functional
- MCP protocol: unverified → pass ▲ functional
- Stability: unverified → 0.23 ▲ functional
- Schema quality: unverified → excellent ▲ functional
- Dependency health: unverified → partial ▲ functional
- Maintenance: unverified → pass ▲ functional
- Licence: ISC functional
- 1 Aug 26 +15
- Malware scan: unverified → pass ▲ security
- 31 Jul 26 −27
- We updated how we score, so this day's move reflects our rubric, not a change to the server See what changed → functional
- 27 Jul 26 51
First indexed and scored.
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 3 Aug 2026 · Analysed npm/@ethora/[email protected]
Provenance none
Ecosystem: npm · Outcome: none
Dependencies 108 packages
108 packages in the resolved dependency tree · 108 deprecated · 32 stale.
The dependency tree was only partially resolved, so these counts may be incomplete.
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.
ethora-agents-activate-v2 ~172
Bind a saved agent as the active AI bot for the current app — copies the agent's config onto the app's bot, replacing whatever was there before (`POST /v2/agents/:agentId/activate`). Does not by itself set `status: "on"` — pair with `ethora-bot-enable-v2` if needed. 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: verify with `ethora-bot-get-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | yes | Id of the saved agent to activate as the app's bot. Get it from `ethora-agents-list-v2`. |
No output schema declared.
No examples provided.
ethora-agents-clone-v2 ~211
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. 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 | yes | Id of the source agent to clone. Get it from `ethora-agents-list-v2`. |
| 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 ~458
Create a new reusable saved agent — a named bot definition (prompt + LLM + RAG settings + identity) that can later be activated onto any app (`POST /v2/agents`). Does not activate it — call `ethora-agents-activate-v2` for that. Returns the created agent including its id. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 422 validation (e.g. duplicate `slug`, unsupported `llmProvider`/`llmModel`).
| Name | Type | Req | Description |
|---|---|---|---|
| botAvatarUrl | string | — | Public URL of the agent's avatar image. |
| botDisplayName | string | — | Display name shown in chat when this agent is the active bot. |
| categories | array | — | Catalogue categories for a public agent. |
| greetingMessage | string | — | Message the agent posts when a conversation starts. |
| isPublished | boolean | — | If true and visibility is public, the agent is listed in the public catalogue. |
| isRAG | boolean | — | If true, the agent retrieves from the app's indexed RAG sources when answering. |
| llmModel | string | — | LLM model id, e.g. `gpt-4o-mini`. Must be available for the chosen provider. |
| llmProvider | string | — | LLM provider, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend. |
| name | string | — | Human-readable agent name. |
| prompt | string | — | System prompt defining the agent's persona and behavior. |
| ragTags | array | — | Restrict RAG retrieval to sources carrying these tags. |
| slug | string | — | URL-safe unique identifier for the agent within the app. Lower-case alphanumerics and dashes. |
| summary | string | — | Short description of what the agent does. |
| trigger | string | — | When the agent responds: `any_message` (every message) or `/bot` (only /bot-prefixed messages). |
| visibility | string | — | `private` (only this app) or `public` (discoverable in the shared agent catalogue). |
No output schema declared.
No examples provided.
ethora-agents-get-v2 ~148
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). 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 | yes | Id of the saved agent to fetch. Get it from `ethora-agents-list-v2`. |
No output schema declared.
No examples provided.
ethora-agents-list-v2 ~101
List the reusable saved agents owned by the current app (`GET /v2/agents`) — 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.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
ethora-agents-update-v2 ~473
Update fields on an existing reusable saved agent (`PUT /v2/agents/:agentId`). Partial update — omitted fields are left unchanged. If the agent is currently activated on the app, changes take effect on the live bot. 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; 422 validation. Related: get `agentId` from `ethora-agents-list-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| agentId | string | yes | Id of the saved agent to update. Get it from `ethora-agents-list-v2`. |
| botAvatarUrl | string | — | Public URL of the agent's avatar image. |
| botDisplayName | string | — | Display name shown in chat when this agent is the active bot. |
| categories | array | — | Catalogue categories for a public agent. |
| greetingMessage | string | — | Message the agent posts when a conversation starts. |
| isPublished | boolean | — | If true and visibility is public, the agent is listed in the public catalogue. |
| isRAG | boolean | — | If true, the agent retrieves from the app's indexed RAG sources when answering. |
| llmModel | string | — | LLM model id, e.g. `gpt-4o-mini`. Must be available for the chosen provider. |
| llmProvider | string | — | LLM provider, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend. |
| name | string | — | Human-readable agent name. |
| prompt | string | — | System prompt defining the agent's persona and behavior. |
| ragTags | array | — | Restrict RAG retrieval to sources carrying these tags. |
| slug | string | — | URL-safe unique identifier within the app. Lower-case alphanumerics and dashes. |
| summary | string | — | Short description of what the agent does. |
| trigger | string | — | When the agent responds: `any_message` (every message) or `/bot` (only /bot-prefixed messages). |
| visibility | string | — | `private` (only this app) or `public` (discoverable in the shared agent catalogue). |
No output schema declared.
No examples provided.
ethora-app-create ~150
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`. 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 ~223
Create a new chat room (MUC room) inside an app the caller owns. If `pinned: true` the room is added to the app's default rooms (new users auto-join; existing users are not). Returns the new room object including its JID. 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 | yes | 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-delete-chat ~195
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. 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-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 ~142
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. 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-list ~108
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. 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 ~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 ~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 ~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 ~222
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. 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 ~246
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. 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 ~323
Update mutable fields on an app the caller owns (displayName, domainName, appDescription, primaryColor, botStatus). Partial update — omitted fields are left unchanged. 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 | — | Long-form description shown on the public app landing page. |
| appId | string | — | 24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`. |
| 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 ~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 ~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 ~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 ~451
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 |
|---|---|---|---|
| botTrigger | string | — | Bot trigger: `/bot` (only /bot-prefixed messages) or `any_message` (every 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 documents to ingest into the new app's RAG sources. |
| enableBot | boolean | — | If true, set the new app's bot to `status: on` (best-effort AI service activation). |
| followLink | boolean | — | For `crawlUrl`: also follow in-domain links (default true). Can ingest many pages. |
| 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. |
| savedAgentId | string | — | Optional id of an existing saved agent to bind as the new app's active bot, instead of configuring prompt/LLM by hand. |
| 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 ~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 ~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 ~214
Turn on the AI bot for an app via B2B auth (sets `botStatus: "on"`). The bot only actually responds if a prompt + LLM are configured (see `ethora-bot-update-v2`) and the backend has an AI service set up. 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: full bot config via `ethora-bot-update-v2`.
| 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 ~145
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. 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 ~191
Turn the AI bot on for an app (sets bot `status: "on"`), optionally setting its trigger. It only actually responds if a prompt + LLM are configured (see `ethora-bot-update-v2`) and the backend has an AI service. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: `ethora-bot-disable-v2` to turn off.
| 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 ~132
Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. 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-update-v2 ~621
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). 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 ~112
Read the public chat-widget / embed configuration for the current app's bot (`GET /v2/bot/widget`) — the widget config and public widget URL metadata needed to embed the bot on a website. 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 ~180
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). 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 ~280
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. 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 ~228
Read the persisted message history of a chat automation session — the conversation produced by `ethora-chats-message-v2` and the bot's replies. Returns the most recent messages (up to `limit`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 400 incomplete `mode`/`nickname`/`roomJid`; 404 room/session not found.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | — | Maximum number of most-recent messages to return. 1–100. Defaults to the backend's default page size. |
| mode | string | — | `private` = 1:1 automation session keyed by `nickname`; `group` = a room identified by `roomJid`. Should match what was used to send. |
| nickname | string | — | Participant nickname for the private automation session. Required when `mode` is `private`. |
| roomJid | string | — | Room JID to read history from. Required when `mode` is `group`. |
No output schema declared.
No examples provided.
ethora-chats-message-v2 ~262
Send a message through the app's chat/bot automation surface — useful for testing the bot or driving automated conversations. Posts a real message; if the app's bot is enabled it reacts to it. `private` mode = 1:1 session keyed by `nickname`, `group` mode = room by `roomJid`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 400 missing `roomJid`/`nickname` for the mode; 404 unknown `roomJid`. Related: read back with `ethora-chats-history-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| mode | string | — | `private` = 1:1 automation session keyed by `nickname`; `group` = a room identified by `roomJid`. Defaults to the backend's default mode. |
| nickname | string | — | Sender/participant nickname for the private automation session. Required when `mode` is `private`. |
| roomJid | string | — | Room JID to post into. Required when `mode` is `group`. Get it from `ethora-app-get-default-rooms`. |
| text | string | yes | Message body to send. |
No output schema declared.
No examples provided.
ethora-configure ~286
Set the Ethora API URL and credentials for this MCP session. Stores values in memory only; each call merges with omitted fields kept. Alternative to env vars (ETHORA_API_URL / ETHORA_APP_JWT / ETHORA_APP_TOKEN / ETHORA_B2B_TOKEN). Auth: none required — this establishes auth material. Errors: only if a value is structurally invalid. Follow with an `ethora-auth-use-*` tool to pick the active mode.
| Name | Type | Req | Description |
|---|---|---|---|
| apiUrl | string | — | Full Ethora API URL including the version path, e.g. `https://api.chat.ethora.com/v1` or `http://localhost:8080/v1`. If you only have the host, set ETHORA_BASE_URL env instead and the server appends… |
| appJwt | string | — | Ethora App JWT, used only to bootstrap login/register in user-auth mode. Usually starts with `JWT `. Secret — never commit it. |
| appToken | string | — | Per-app appToken for app-scoped flows (broadcast, sources, bot). Setting this makes app-token auth available via `ethora-auth-use-app`. Secret. |
| b2bToken | string | — | B2B server token for tenant-actor `x-custom-token` auth (a JWT with `type=server`). Required for B2B provisioning flows. Secret. |
No output schema declared.
No examples provided.
ethora-doctor ~124
Diagnose the session: validate the config is internally consistent for the active auth mode and ping the Ethora API (`GET /v1/ping`). Returns `{ state, checks, ping, suggestions }`. Auth: none required; report is tailored to whatever credentials are set. Errors: rarely throws — instead returns `suggestions` and a `ping.ok: false` block when the API is unreachable.
| Name | Type | Req | Description |
|---|---|---|---|
| timeoutMs | integer | — | HTTP timeout in milliseconds for the ping request. Defaults to 3000. Raise it on slow links, lower it to fail fast. |
No output schema declared.
No examples provided.
ethora-files-delete-v2 ~113
Permanently delete one of the authenticated user's files by id (`DELETE /v2/files/:id`). Removes the record and its stored content; not reversible. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 403 not owned by the user; 404 unknown `id`. Related: get ids from `ethora-files-get-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| id | string | yes | Id of the file to delete. Get it from `ethora-files-get-v2`. |
No output schema declared.
No examples provided.
ethora-files-get-v2 ~108
List the authenticated user's files, or fetch one file's metadata by id (`GET /v2/files`). Returns an array when `id` is omitted, a single record when given. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 404 unknown `id` or not owned by the user.
| Name | Type | Req | Description |
|---|---|---|---|
| id | string | — | File id to fetch a single record. Omit to list all files owned by the logged-in user. |
No output schema declared.
No examples provided.
ethora-files-upload-v2 ~134
Upload 1–5 files to the authenticated user's Ethora file storage (`POST /v2/files`). Each upload is a new record (no overwrite-by-name); files passed as base64, 50MB max each. Auth: user-auth mode with an active user session (`ethora-user-login` first). Errors: 401 not logged in; 413 size limit exceeded; 422 unsupported mime type. Related: manage with `ethora-files-get-v2` / `ethora-files-delete-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| files | array | yes | 1 to 5 files to upload in this call. |
No output schema declared.
No examples provided.
ethora-generate-b2b-bootstrap-runbook ~186
Generate a human-readable runbook listing this server's tool calls in the right order for a B2B bootstrap, with example payloads. Documentation only — does not write any file or execute any step. Auth: none required — pure text generator, no API calls. Errors: effectively none. Related: to actually run the sequence use `ethora-run-recipe` or `ethora-b2b-app-bootstrap-ai`.
| Name | Type | Req | Description |
|---|---|---|---|
| apiUrl | string | — | Ethora API base URL to show in the runbook's configure step. Omit to emit a placeholder. |
| crawlUrl | string | — | Website URL to show in the runbook's source-ingest step. Omit to emit a placeholder. |
| displayName | string | — | App display name to show in the runbook's create-app step. Omit to emit a placeholder. |
No output schema declared.
No examples provided.
ethora-generate-chat-component-app-tsx ~208
Generate a ready-to-paste React `App.tsx` snippet that mounts `@ethora/chat-component`. Returns `{ filename: "App.tsx", snippet }`; unpassed values are emitted as placeholders. Does not write any file. Auth: none required — pure code generator, no API calls. Errors: effectively none. Security note: the snippet includes `appToken` inline only as a quickstart convenience — do not ship hardcoded tokens to production.
| Name | Type | Req | Description |
|---|---|---|---|
| apiUrl | string | — | Ethora API base URL to embed in the snippet, e.g. `https://api.chat.ethora.com/v1`. Omit to emit a placeholder. |
| appToken | string | — | appToken to embed in the snippet for quickstart testing. Omit to emit a placeholder. Do NOT hardcode real tokens in production source. |
| roomJid | string | — | Room JID to open on load. Omit to emit a commented-out placeholder. |
No output schema declared.
No examples provided.
ethora-generate-env-examples ~144
Generate `.env.example` templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. Returns `{ target, template }` when `target` is given, or `{ templates }` with all three. Placeholder values only; does not write any file. Auth: none required — pure text generator, no API calls. Errors: effectively none.
| Name | Type | Req | Description |
|---|---|---|---|
| target | string | — | Which template to return: `frontend-chat-component` (Vite env), `backend-sdk` (@ethora/sdk-backend env), or `mcp` (this server's env). Omit to return all three. |
No output schema declared.
No examples provided.
ethora-help ~113
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-run-recipe`.
| Name | Type | Req | Description |
|---|---|---|---|
| goal | string | — | Goal hint to tailor the recommendations and recipe list. Omit or use `auto` to get recommendations inferred from the current session state. |
No output schema declared.
No examples provided.
ethora-run-recipe ~278
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). Use `dryRun: true` to preview resolved steps. Omit `recipeId` to list runnable recipes for a `goal`. Auth: depends on the recipe's steps — configure those first (see `ethora-help`). Errors: stops at the first failing step and returns the partial log; a missing required `vars` entry fails fast before any step runs.
| Name | Type | Req | Description |
|---|---|---|---|
| dryRun | boolean | — | If true, resolve and return the step list with `vars` substituted but execute nothing. Use this to preview a recipe before running it for real. |
| goal | string | — | Goal scope used to look up recipes when `recipeId` is omitted. Defaults to `auto`. |
| recipeId | string | — | Id of the recipe to run. Omit to instead list the runnable recipes for the selected `goal` (get ids from `ethora-help`). |
| vars | object | — | Key/value substitutions injected into recipe steps (e.g. appId, appToken, b2bToken, appJwt, email, password, apiUrl). A recipe declares which vars it requires; missing required vars fail the run befo… |
No output schema declared.
No examples provided.
ethora-sources-docs-delete ~182
Remove a previously ingested document from an app's RAG sources by `docId` (legacy user-auth route). Deletes the document record and its embeddings; not reversible. Auth: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`; app-token/B2B uses `ethora-sources-docs-delete-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId the document belongs to. Optional — defaults to the app set via `ethora-app-select`. |
| docId | string | yes | Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`. |
No output schema declared.
No examples provided.
ethora-sources-docs-delete-v2 ~189
Remove a previously ingested document from an app's RAG sources by `docId` (app-token / B2B variant of `ethora-sources-docs-delete`). Deletes the document record and its embeddings; not reversible. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| docId | string | yes | Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`. |
No output schema declared.
No examples provided.
ethora-sources-docs-list-v2 ~162
List an app's ingested documents, including each document's id, name, and current RAG tags. Their ids feed `ethora-sources-docs-tags-update-v2` and `ethora-sources-docs-delete-v2`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; empty list if nothing has been uploaded. Related: website-sources equivalent is `ethora-sources-site-list-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId to list documents for. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
No output schema declared.
No examples provided.
ethora-sources-docs-tags-update-v2 ~242
Set the RAG retrieval tags on an ingested document — replaces the document's tag set with the provided `tags` array (not additive; pass `[]` to clear all). Tags let the bot's `ragTags` narrow retrieval. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`; website-source equivalent is `ethora-sources-site-tags-update-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| docId | string | yes | Id of the ingested document to tag. Get it from `ethora-sources-docs-list-v2`. |
| tags | array | yes | The complete desired tag set for this document (replaces any existing tags). Up to 50 tags; pass `[]` to clear all. |
No output schema declared.
No examples provided.
ethora-sources-docs-upload ~170
Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (legacy user-auth route). Async — content becomes queryable once indexing finishes; files passed as base64, 50MB max each. Auth: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 413 too large; 422 unsupported document type. Related: app-token/B2B flows use `ethora-sources-docs-upload-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId to ingest into. Optional — defaults to the app set via `ethora-app-select`. |
| files | array | yes | 1 to 5 documents to ingest in this call. |
No output schema declared.
No examples provided.
ethora-sources-docs-upload-v2 ~200
Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-sources-docs-upload`). Async — content becomes queryable once indexing finishes; files passed as base64, 50MB max each. 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-sources-docs-list-v2`, `ethora-sources-docs-delete-v2`.
| Name | Type | Req | Description |
|---|---|---|---|
| appId | string | — | 24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode. |
| files | array | yes | 1 to 5 documents to ingest in this call. |
No output schema declared.
No examples provided.