read-only safe to auto-approve; needs the
read OAuth scope
write changes data; needs write
destructive deletes or revokes; needs admin, clients should confirm first
Session and help (8)
Orientation and diagnostics. Start every session with Session Status; ask Help and Next Steps whenever you are lost.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Session Status | ethora-status | Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present (booleans like hasAppJwt - values never echoed), the selected... | read-only | none |
| Connection Doctor | ethora-doctor | Diagnose the session: validate the config is internally consistent for the active auth mode and ping the Ethora API (GET /v1/ping). | read-only | none |
| Help and Next Steps | ethora-help | Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends next tool calls + recipes based on current session state. | read-only | none |
| Run Recipe | ethora-run-recipe | Execute a built-in recipe - an ordered sequence of this server’s own tool calls - by id. | write | user |
| Configure Connection | ethora-configure | Set the Ethora API URL and credentials for this MCP session. | write | none |
| Use User Auth | ethora-auth-use-user | Switch this session’s active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. | write | user |
| Use App Token Auth | ethora-auth-use-app | Switch this session’s active auth mode to app-token, so subsequent app-scoped calls authenticate with the configured appToken. | write | app token |
| Use B2B Auth | ethora-auth-use-b2b | Switch this session’s active auth mode to B2B, so subsequent calls authenticate as a tenant actor via the x-custom-token header. | write | B2B token |
Accounts and API keys (5)
Sign in, or let an agent create its own account and receive a revocable API key with no human step.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Register Account | ethora-user-register | Create a new Ethora user account by email + first/last name, then log in and bind the session. | write | user |
| Log In | ethora-user-login | Authenticate as an existing Ethora user with email + password. | write | user |
| Create API Key | ethora-api-key-create | Mint a long-lived, revocable API key for the currently logged-in user. | write | user |
| List API Keys | ethora-api-key-list | List the current user’s API keys (id, name, createdAt, expiresAt). | read-only | user |
| Revoke API Key | ethora-api-key-revoke | Revoke one of the current user’s API keys by id. | destructive | user |
Apps (tenants) (11)
Each app is an isolated chat workspace with its own users, rooms, agents and knowledge base.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Create App | ethora-app-create | Create a new Ethora app (tenant) owned by the currently logged-in user. | write | user |
| List Apps | ethora-app-list | List all Ethora apps (tenants) owned by the currently logged-in user. | read-only | user |
| Select App | ethora-app-select | Set the current app context for this session so app-scoped tools can omit their appId argument. | write | none |
| Update App | ethora-app-update | Update mutable fields on an app the caller owns (displayName, domainName, appDescription, primaryColor, botStatus). | write | user |
| Delete App | ethora-app-delete | Permanently delete an Ethora app the caller owns - removes its chat rooms, files, indexed RAG sources, and bot config; end users are immediately signed out. | destructive | user |
| Export App | ethora-app-export-v2 | Export an App as a portable bundle (GET /v2/apps/:appId/export). | read-only | user |
| Import App | ethora-app-import-v2 | Import an App from a bundle produced by ethora-app-export-v2 (POST /v2/apps/import, application/json body IS the bundle). | write | user |
| Create App Token | ethora-app-tokens-create-v2 | Mint a new app token for an app. | write | B2B token |
| List App Tokens | ethora-app-tokens-list-v2 | 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... | read-only | B2B token |
| Rotate App Token | ethora-app-tokens-rotate-v2 | Rotate an app token: revoke an existing token and issue a replacement in one step. | destructive | B2B token |
| Revoke App Token | ethora-app-tokens-revoke-v2 | Permanently revoke an app token by tokenId - it stops working immediately; any client, SDK, or MCP session still using it gets auth failures. | destructive | B2B token |
Rooms and messages (12)
Create rooms, post and broadcast messages, read history, search, and count unread messages per user.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Create Chat Room | ethora-app-create-chat | Create a new chat room (MUC room) inside an app the caller owns. | write | user |
| Delete Chat Room | ethora-app-delete-chat | Permanently delete a chat room from an app the caller owns - removes the MUC room, its message archive, and all member affiliations. | destructive | user |
| Get Default Rooms | ethora-app-get-default-rooms | List the default chat rooms (MUC rooms) of the currently selected Ethora app - every new user auto-joins these. | read-only | user |
| Get Default Rooms for App | ethora-app-get-default-rooms-with-app-id | List the default chat rooms of a specific Ethora app, passed via appId (or the currently selected app). | read-only | user |
| Send Chat Message | ethora-chats-message-v2 | Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). | write | user |
| Get Chat History | ethora-chats-history-v2 | Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). | read-only | user |
| Broadcast Message | ethora-chats-broadcast-v2 | 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. | write | app token or B2B |
| Get Broadcast Job | ethora-chats-broadcast-job-v2 | Fetch the current status and per-room results of a broadcast job by jobId (one-shot, no polling). | read-only | app token or B2B |
| Wait for Broadcast Job | ethora-wait-broadcast-job-v2 | Block until a broadcast job reaches a terminal state (completed or failed) or until timeoutMs - read-only polling wrapper around ethora-chats-broadcast-job-v2. | read-only | app token or B2B |
| Search Messages | ethora-messages-search-v2 | Search an App’s chat messages (GET /v2/apps/:appId/messages/search). | read-only | user |
| Get Message Context | ethora-messages-context-v2 | Fetch the messages surrounding a target message (GET /v2/apps/:appId/chats/:chatId/messages/context). | read-only | user |
| Get Unread Counts | ethora-unread-counts-v2 | Batch per-room unread message counts for a set of users (POST /v2/apps/:appId/users/unread-counts). | read-only | user |
AI agents (18)
Create reusable agent personas, put them in rooms, make one the default responder, and inspect the live bot instances.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Create Agent | ethora-agents-create-v2 | Create a reusable AI agent (POST /v2/apps/:appId/agents). | write | user |
| List Agents | ethora-agents-list-v2 | 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. | read-only | app token |
| Get Agent | ethora-agents-get-v2 | Fetch one reusable saved agent’s full config by id (GET /v2/agents/:agentId) - prompt, LLM, RAG settings, visibility. | read-only | app token |
| Update Agent | ethora-agents-update-v2 | Update a saved AI agent (PUT /v2/agents/:agentId). | write | user |
| Clone Agent | ethora-agents-clone-v2 | Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (POST /v2/agents/:agentId/clone). | write | app token |
| Delete Agent | ethora-agents-delete-v2 | Delete an Agent (DELETE /v2/agents/:idOrAddress). | destructive | user |
| Export Agent | ethora-agents-export-v2 | Export an Agent as a portable bundle (GET /v2/agents/:idOrAddress/export). | read-only | user |
| Import Agent | ethora-agents-import-v2 | Import an Agent from a bundle produced by ethora-agents-export-v2 (POST /v2/agents/import, application/json body IS the bundle). | write | user |
| Activate Agent for Widget | ethora-agents-activate-v2 | 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. | write | user |
| Invite Agent to Chat | ethora-agent-invite-to-chat | Invite an Agent into a chat room. | write | user |
| Set Agent Visibility | ethora-agent-set-visibility | Set an Agent’s visibility (private | unlisted | public). | write | user |
| Set Agent Prompt | ethora-agent-soul-set | Replace an Agent’s SOUL.MD with the provided markdown. | write | user |
| Append to Agent Prompt | ethora-agent-soul-append | Append a fragment to an Agent’s SOUL.MD (its evolving identity / private notes). | write | user |
| List Bot Instances | ethora-bot-instances-list | List BotInstances. | read-only | user |
| Bot Instance Status | ethora-bot-instance-status | Turn a specific BotInstance on or off. | read-only | user |
| Diagnose Bot Instance | ethora-bot-instance-diag | Diagnose a specific BotInstance for an Agent (GET /v2/agents/:idOrAddress/bot-instances/:botInstanceId/diag). | read-only | user |
| Send Test Message to Bot | ethora-bot-instance-test-message | Send a test message from a BotInstance (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/test-message). | write | user |
| Remove Bot from Chat | ethora-bot-instance-leave-chat | Remove a BotInstance from a chat room (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/leave-chat). | destructive | user |
Website chat widget (2)
Generate the embed snippet and a React starter so the agent you just built answers on a website.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Widget Embed Snippet | ethora-widget-embed-snippet | Generate the <script> tag that embeds the Ethora AI chat widget (the floating launcher + chat panel that website visitors use) for an app, plus the prerequisites that must hold before it... | read-only | none |
| Generate Chat Component App.tsx | ethora-generate-chat-component-app-tsx | Generate a ready-to-paste React App.tsx snippet that mounts @ethora/chat-component. | read-only | none |
RAG sources (knowledge base) (14)
Crawl websites and upload documents into an app’s retrieval index, tag them, reindex and prune.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Crawl Website Source | ethora-sources-site-crawl-v2 | Crawl a website URL and ingest its content into an app’s RAG sources (app-token / B2B variant of ethora-sources-site-crawl). | write | app token or B2B |
| Crawl Website Source and Wait | ethora-sources-site-crawl-v2-wait | Crawl a website URL and block until the server finishes - a single-call, long-timeout variant of ethora-sources-site-crawl-v2 (same crawl + embed effect). | write | app token or B2B |
| Reindex Website Source | ethora-sources-site-reindex-v2 | Re-crawl and re-embed a previously crawled URL by its urlId, refreshing its RAG content (app-token / B2B variant of ethora-sources-site-reindex). | write | app token or B2B |
| Reindex Website Source and Wait | ethora-sources-site-reindex-v2-wait | Re-crawl and re-embed a previously crawled URL and block until the server finishes - a single-call, long-timeout variant of ethora-sources-site-reindex-v2 (same refresh effect). | write | app token or B2B |
| List Website Sources | ethora-sources-site-list-v2 | List an app’s crawled website sources, including each source’s id, URL, and current RAG tags. | read-only | app token or B2B |
| Update Website Source Tags | ethora-sources-site-tags-update-v2 | Set the RAG retrieval tags on a crawled website source - replaces the source’s tag set with the provided tags array (not additive; pass [] to clear all). | write | app token or B2B |
| Delete Website Source URL | ethora-sources-site-delete-url-v2 | Remove a single crawled URL from an app’s RAG sources, matched by its exact url string (app-token / B2B variant of ethora-sources-site-delete-url). | destructive | app token or B2B |
| Delete Website Source URLs | ethora-sources-site-delete-url-v2-batch | Bulk-remove crawled website sources (1-100) from an app in one call, matched by their source record ids. | destructive | app token or B2B |
| Upload Knowledge Document | ethora-sources-docs-upload-v2 | Upload documents (1-5; PDF, text, etc.) into an app’s RAG sources (app-token / B2B variant of ethora-sources-docs-upload). | write | app token or B2B |
| List Knowledge Documents | ethora-sources-docs-list-v2 | List an app’s ingested documents, including each document’s id, name, and current RAG tags. | read-only | app token or B2B |
| Update Knowledge Document Tags | ethora-sources-docs-tags-update-v2 | 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). | write | app token or B2B |
| Delete Knowledge Document | ethora-sources-docs-delete-v2 | Remove a previously ingested document from an app’s RAG sources by docId (app-token / B2B variant of ethora-sources-docs-delete). | destructive | app token or B2B |
| Upload Knowledge Document (Legacy) | ethora-sources-docs-upload | Upload documents (1-5; PDF, text, etc.) into an app’s RAG sources (legacy user-auth route). | write | user |
| Delete Knowledge Document (Legacy) | ethora-sources-docs-delete | Remove a previously ingested document from an app’s RAG sources by docId (legacy user-auth route). | destructive | user |
Users and files (6)
Provision end users in bulk and manage the signed-in user’s file storage.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Batch Create Users | ethora-users-batch-create-v2 | Provision many Ethora users (1-100) in one asynchronous batch job - the bulk equivalent of ethora-user-register. | write | B2B token |
| Get Users Batch Job | ethora-users-batch-job-v2 | Fetch the current status and per-user results of a users batch job by jobId (one-shot, no polling). | read-only | B2B token |
| Wait for Users Batch Job | ethora-wait-users-batch-job-v2 | Block until a users batch job reaches a terminal state (completed or failed) or timeoutMs - read-only polling wrapper around ethora-users-batch-job-v2. | read-only | B2B token |
| Upload File | ethora-files-upload-v2 | Upload 1-5 files to the authenticated user’s Ethora file storage (POST /v2/files). | write | user |
| Get File | ethora-files-get-v2 | List the authenticated user’s files, or fetch one file’s metadata by id (GET /v2/files). | read-only | user |
| Delete File | ethora-files-delete-v2 | Permanently delete one of the authenticated user’s files by id (DELETE /v2/files/:id). | destructive | user |
B2B provisioning (5)
One-call orchestrators for integrators: create an app, mint tokens, index sources and switch the agent on, with a runbook to match.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Create App (B2B) | ethora-b2b-app-create | Create a new Ethora app (tenant) server-side using B2B auth - the partner/integrator equivalent of ethora-app-create. | write | B2B token |
| Provision App (B2B) | ethora-b2b-app-provision | One-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. | write | B2B token |
| Bootstrap AI App (B2B) | ethora-b2b-app-bootstrap-ai | One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. | write | B2B token |
| Generate B2B Bootstrap Runbook | ethora-generate-b2b-bootstrap-runbook | Generate a human-readable runbook listing this server’s tool calls in the right order for a B2B bootstrap, with example payloads. | read-only | none |
| Generate Env Examples | ethora-generate-env-examples | Generate .env.example templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. | read-only | none |
Legacy per-app bot (6)
For apps created in the dashboard before the agents framework. New apps use the AI agents group instead.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Get Legacy Bot | ethora-bot-get-v2 | Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. | read-only | app token or B2B |
| Update Legacy Bot | ethora-bot-update-v2 | Configure the AI bot for an app - prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. | write | app token or B2B |
| Enable Legacy Bot | ethora-bot-enable-v2 | Enable the LEGACY per-app aiBot using app-token or B2B auth. | write | user |
| Disable Legacy Bot | ethora-bot-disable-v2 | Turn the AI bot off for an app (sets bot status: "off") - it stops responding. | write | app token or B2B |
| Get Legacy Bot Widget | ethora-bot-widget-v2 | 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. | read-only | app token |
| Enable Legacy Bot (B2B) | ethora-b2b-bot-enable | Enable the LEGACY per-app aiBot (B2B auth). | write | user |
Documentation search (2)
The ChatGPT connector convention: search the server’s own reference and fetch a section by id. Works without signing in.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Search Docs | search | Search the Ethora documentation and tool reference: auth model (app JWT vs app token vs B2B token vs API keys), hosted-server getting started, chat-component and backend SDK quickstarts,... | read-only | none |
| Fetch Doc | fetch | Fetch the full text of a documentation section or tool reference entry by the id returned from search (e.g. | read-only | none |
Wallet (1)
Read-only balance lookup. No tool on the hosted server moves money or tokens.
| Tool | Name | What it does | Access | Auth |
|---|---|---|---|---|
| Get Wallet Balance | ethora-wallet-get-balance | Read the authenticated user’s on-chain ERC-20 wallet balance(s). | read-only | user |
Resources and prompts
Besides tools, the server ships loadable documentation resources and reusable prompts so an assistant can read the integration guides into its context instead of guessing.
ethora://docs/auth-mapappJwt vs appToken vs b2bTokenethora://docs/chat-component/quickstartVite/Next quickstart + replacing demo tokensethora://docs/sdk-backend/quickstart@ethora/sdk-backend quickstartethora://docs/recipesCommon MCP recipesethora-vite-quickstartExplains how to add chat component to a Vite app, and how to avoid demo tokens in production.ethora-nextjs-quickstartExplains how to add chat component to a Next.js app and handle auth safely.ethora-backend-sdk-quickstartShows how to integrate Ethora backend SDK in a Node.js backend.ethora-auth-mapExplains appJwt vs appToken vs b2bToken and when to use each.ethora-recipesCommon MCP tool sequences for local user-auth and server-side B2B/app-token flows.ethora-agents-quickstartEnd-to-end recipe for creating Agents, indexing their RAG, marking them public, inviting them into rooms, and running the two-agents-in-one-room demo.
