Ethora MCP CLI

An MCP (Model Context Protocol) CLI/server that connects popular MCP clients to theEthoraplatform — an open-sourcechat & messaging platform with a built-in AI agent / chatbot framework. This runs locally on a developer machine via stdio rather than as a hosted Ethora service.
Use it fromCursor,VS Code MCP,Claude Desktop, orWindsurf/Clineto manage apps and chat rooms, broadcast messages, deploy AI agents / chatbots with RAG sources, and automate B2B provisioning workflows. (ERC-20 wallet tools are also included — see the tool list below.)

- Talk to the Ethora platform directly from your IDE or AI agent client (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).
- Bothuser-authflows (login/register, files, owner/admin endpoints) andB2B / app-tokenflows (tenant provisioning, broadcast jobs, async user batches, AI bot config).
- Built-in recipes, prompts, and generators for the most common Ethora workflows (Vite/Next chat-component setup, B2B bootstrap, AI-bot enablement, RAG sources).
- Standard tool response envelope ({ ok, ts, meta, data | error }) so agent code can reason about success/failure consistently.

🚦 Just trying it? (60-second quickstart)

Don't read the auth modes yet. Once the server is connected in your client, ask your agent to run, in order:
- ethora-doctor— confirms the server is up and can reach the Ethora API. No credentials needed.
- ethora-configurewith yourappJwt→ethora-auth-use-user→ethora-user-loginwith an email + password.
- ethora-app-list— you're in; this lists your apps.

- developers trying Ethora locally
- tenant admins / app owners using MCP manually
- flows that start withethora-user-login

- configureETHORA_APP_JWTonce for login/register bootstrap
- switch toethora-auth-use-user
- callethora-user-login
- use user-auth tools such as files and legacy owner/admin endpoints

- permanent backend integrations
- partner provisioning flows
- autonomous agents operating Ethora without a human user session

- configureETHORA_B2B_TOKEN
- switch toethora-auth-use-b2bfor explicit tenant-actor/v2/apps/:appId/...routes
- optionally switch intoethora-auth-use-appafterethora-app-selectwhen you want app-scoped convenience routes powered byappToken

- first-time local use usually starts withUser Auth
- repeatable automation usually starts withB2B, then often moves intoapp-tokenmode for one selected app

Prompts & Resources (P2: dev-facing docs)

- Resources(loadable docs into context)

- ethora://docs/auth-map— appJwt vs appToken vs b2bToken
- ethora://docs/chat-component/quickstart— Vite/Next quickstart + replacing demo tokens
- ethora://docs/sdk-backend/quickstart— backend integration quickstart
- ethora://docs/recipes— common tool sequences (broadcast/sources/files/bot)

- ethora-auth-map
- ethora-vite-quickstart
- ethora-nextjs-quickstart
- ethora-backend-sdk-quickstart
- ethora-recipes

- ethora-generate-chat-component-app-tsx— ready-to-pasteApp.tsxsnippet for@ethora/chat-component
- ethora-generate-env-examples—.env.exampletemplates for:

- frontend chat component
- backend SDK integration
- MCP usage (ETHORA_API_URL,ETHORA_APP_JWT,ETHORA_B2B_TOKEN)

Tip: to list runnable recipes without callingethora-help, callethora-run-recipewithgoal: "auto"and omitrecipeId.

- ethora-configure— set API URL plus App JWT / B2B token / appToken for this MCP session
- ethora-status— show configured API URL, active auth mode, and which credentials are present
- ethora-help— task-oriented help (recommended next calls + “one-click recipes” based on current state)
- ethora-run-recipe— execute a built-in recipe by id (sequential steps; no shell, no file writes)
- ethora-doctor— validate config + ping the configured Ethora API for both user and B2B usage
- ethora-app-select— select current appId and optionally set appToken
- ethora-auth-use-app— switch to app-token auth mode for app-scoped operations
- ethora-auth-use-user— switch to user-session auth mode
- ethora-auth-use-b2b— switch to tenant-actor B2Bx-custom-tokenauth mode

- ethora-chats-broadcast-v2— enqueue broadcast job using app-token auth or B2B + explicitappId
- ethora-chats-broadcast-job-v2— get broadcast job status/results using app-token auth or B2B + explicitappId
- ethora-wait-broadcast-job-v2— poll broadcast job until completed/failed using app-token auth or B2B + explicitappId
- ethora-chats-message-v2— send a test/automation message through the app chat surface (requires app-token auth)
- ethora-chats-history-v2— read persisted automation/test history for private or group sessions (requires app-token auth)

- ethora-users-batch-create-v2— create async users batch job (requires B2B auth)
- ethora-users-batch-job-v2— get users batch job status/results (requires B2B auth)
- ethora-wait-users-batch-job-v2— poll users batch job until completed/failed (requires B2B auth)

-

ethora-bot-get-v2— get bot status/settings using app-token auth or B2B + explicitappId

ethora-bot-update-v2— update bot settings using app-token auth or B2B + explicitappId

ethora-bot-enable-v2— enable bot using app-token auth or B2B + explicitappId

ethora-bot-disable-v2— disable bot using app-token auth or B2B + explicitappId

ethora-bot-widget-v2— get widget/embed config and public widget URL metadata (app-token auth)

ethora-agents-list-v2— list reusable saved agents for the current app owner (app-token auth)

ethora-agents-get-v2— get one reusable saved agent (app-token auth)

ethora-agents-create-v2— create a reusable saved agent (app-token auth)

ethora-agents-update-v2— update a reusable saved agent (app-token auth)

ethora-agents-clone-v2— clone a reusable saved agent (app-token auth)

ethora-agents-activate-v2— bind a saved agent as the active bot for the selected app (app-token auth)

ethora-bot-message-v2— compatibility alias forethora-chats-message-v2

ethora-bot-history-v2— compatibility alias forethora-chats-history-v2

ethora-files-upload-v2— upload files (requires user auth)

ethora-files-get-v2— list/get files (requires user auth)

ethora-files-delete-v2— delete file by id (requires user auth)

- ethora-sources-site-crawl— crawl a URL (requires user auth)
- ethora-sources-site-reindex— reindex URL by urlId (requires user auth)
- ethora-sources-site-delete-url— delete by URL (requires user auth)
- ethora-sources-site-delete-url-v2— batch delete URLs (requires user auth)
- ethora-sources-docs-upload— upload docs for ingestion (requires user auth)
- ethora-sources-docs-delete— delete ingested doc by id (requires user auth)
- ethora-sources-site-crawl-v2— crawl a URL using app-token auth or B2B + explicitappId
- ethora-sources-site-reindex-v2— reindex URL by urlId using app-token auth or B2B + explicitappId
- ethora-sources-site-crawl-v2-wait— single-call long-timeout helper for crawl (app-token auth)
- ethora-sources-site-reindex-v2-wait— single-call long-timeout helper for reindex (app-token auth)
- ethora-sources-site-list-v2— list crawled site sources and current tags using app-token auth or B2B + explicitappId
- ethora-sources-site-tags-update-v2— set/update tags for a crawled site source using app-token auth or B2B + explicitappId
- ethora-sources-site-delete-url-v2— delete one crawled URL by URL using app-token auth or B2B + explicitappId
- ethora-sources-site-delete-url-v2-batch— batch delete crawled source records by id using app-token auth or B2B + explicitappId
- ethora-sources-docs-upload-v2— upload docs for ingestion using app-token auth or B2B + explicitappId
- ethora-sources-docs-list-v2— list indexed documents and current tags using app-token auth or B2B + explicitappId
- ethora-sources-docs-tags-update-v2— set/update tags for an indexed document using app-token auth or B2B + explicitappId
- ethora-sources-docs-delete-v2— delete doc by id using app-token auth or B2B + explicitappId

- ethora-user-login— login user (email + password)
- ethora-user-register— register user (email + first/last name)

- ethora-app-create— create app
- ethora-app-update— update app
- ethora-app-delete— delete app
- ethora-app-list— list apps
- ethora-b2b-app-create— create app using B2B auth (x-custom-token)
- ethora-b2b-app-bootstrap-ai— create app → index sources → configure/enable bot, including runtime LLM selection (B2B automation)
- ethora-app-tokens-list-v2— list app token metadata (B2B auth)
- ethora-app-tokens-create-v2— create new app token (returned once) (B2B auth)
- ethora-app-tokens-rotate-v2— rotate token (revoke old, return new once) (B2B auth)
- ethora-app-tokens-revoke-v2— revoke token by tokenId (idempotent) (B2B auth)
- ethora-b2b-app-provision— create app + create tokens + provision rooms + configure bot, including runtime LLM selection (B2B orchestrator)

- ethora-app-get-default-rooms— list default rooms
- ethora-app-get-default-rooms-with-app-id— rooms for a given app
- ethora-app-create-chat— create chat for app
- ethora-app-delete-chat— delete chat

- ethora-wallet-get-balance— get balance
- ethora-wallet-erc20-transfer— send ERC-20 tokens

Tool names above reflect the functional areas exposed by the server. Your exact tool names may vary slightly by version; run the client’s “list tools” to confirm.

Before you begin, ensure you have the following:

- Node.js installed on your system (recommended version 18.x or higher).

The server is distributed as an npm package and is typically launched by MCP clients vianpx:

This MCP server supports both the local user-auth flow and the server-side B2B flow.

- Ethora API URL(where to send requests)
- Ethora App JWT(used only for login/register bootstrap in user-auth mode)
- Ethora B2B Token(used for tenant-actor server-to-server flows)

- viaenv vars, or
- at runtime via theethora-configuretool (in-memory; resets when MCP process restarts)

- ETHORA_API_URL: full API URL (example:https://api.chat.ethora.com/v1,http://localhost:8080/v1)
- ETHORA_BASE_URL: base host URL (example:https://api.chat.ethora.com,http://localhost:8080)
If provided, the server will default to.../v1.
- ETHORA_APP_JWT: App JWT string, usually starting withJWT ...
- ETHORA_B2B_TOKEN: B2B server token forx-custom-tokenauth (JWT withtype=server)
- ETHORA_MCP_ENABLE_DANGEROUS_TOOLS: enable destructive tools (default: disabled). Set totrueto expose:

- app deletion tools
- wallet transfer tools
- bulk delete tools

Security:nevercommit App JWTs, B2B tokens, or appTokens to git. Configure them via env vars, the MCP client secret store, or your own backend.

All tools return JSON in a consistent envelope:

- Success:{ ok: true, ts, meta, data }
- Error:{ ok: false, ts, meta, error }, whereerrorincludes:

- code: stable string (prefer APIcode, otherwise inferred)
- httpStatus: HTTP status when the failure came from an API call
- requestId: request/correlation id if returned by API
- hint: 1-line “what to do next”

Every client runs the same thing —npx -y @ethora/mcp-serverover stdio. One-click buttons exist forCursorandVS Code(top of this README). For the rest it's a short config block or a one-line command.