Ethora MCP Server (Model Context Protocol)

One-click install for Cursor and VS Code (buttons above). For Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf, and Cline, see Using with MCP Clients below.

An MCP (Model Context Protocol) CLI/server that connects popular MCP clients to the Ethora platform — an open-source chat & 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 from Cursor, VS Code MCP, Claude Desktop, or Windsurf/Cline to 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.)

Part of the Ethora SDK ecosystem — see all SDKs, tools, and sample apps. Follow cross-SDK updates in the Release Notes.

• npm: https://www.npmjs.com/package/@ethora/mcp-server
• Default Ethora API: https://api.chat.ethora.com/v1 (Swagger: https://api.chat.ethora.com/api-docs/#/)

✨ What you get

• Talk to the Ethora platform directly from your IDE or AI agent client (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).
• Both user-auth flows (login/register, files, owner/admin endpoints) and B2B / app-token flows (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:

1. ethora-doctor — confirms the server is up and can reach the Ethora API. No credentials needed.
2. ethora-configure with your appJwt → ethora-auth-use-user → ethora-user-login with an email + password.
3. ethora-app-list — you're in; this lists your apps.

That's the local-developer path. Need server-side automation instead? Jump to B2B mode. Lost at any point, call ethora-help — it reads your current state and tells you the next call.

🔐 Two typical usage modes

1) User Auth mode

Best for:

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

How it works:

• configure ETHORA_APP_JWT once for login/register bootstrap
• switch to ethora-auth-use-user
• call ethora-user-login
• use user-auth tools such as files and legacy owner/admin endpoints

2) B2B mode

Best for:

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

How it works:

• configure ETHORA_B2B_TOKEN
• switch to ethora-auth-use-b2b for explicit tenant-actor /v2/apps/:appId/... routes
• optionally switch into ethora-auth-use-app after ethora-app-select when you want app-scoped convenience routes powered by appToken

Rule of thumb:

• first-time local use usually starts with User Auth
• repeatable automation usually starts with B2B, then often moves into app-token mode 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)
• Prompts
  • ethora-auth-map
  • ethora-vite-quickstart
  • ethora-nextjs-quickstart
  • ethora-backend-sdk-quickstart
  • ethora-recipes

Generators (no shell, no file writes)

• ethora-generate-chat-component-app-tsx — ready-to-paste App.tsx snippet for @ethora/chat-component
• ethora-generate-env-examples — .env.example templates for:
  • frontend chat component
  • backend SDK integration
  • MCP usage (ETHORA_API_URL, ETHORA_APP_JWT, ETHORA_B2B_TOKEN)
• ethora-generate-b2b-bootstrap-runbook — minimal “call these MCP tools in order” runbook for B2B bootstrap

Tip: to list runnable recipes without calling ethora-help, call ethora-run-recipe with goal: "auto" and omit recipeId.

• Session / Config

  • 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 B2B x-custom-token auth mode

• Chats (v2)

  • ethora-chats-broadcast-v2 — enqueue broadcast job using app-token auth or B2B + explicit appId
  • ethora-chats-broadcast-job-v2 — get broadcast job status/results using app-token auth or B2B + explicit appId
  • ethora-wait-broadcast-job-v2 — poll broadcast job until completed/failed using app-token auth or B2B + explicit appId
  • 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)

• Users (v2 async batch)

  • 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)

• Files (v2)

• Bot / Agent (v2)

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

  • ethora-bot-update-v2 — update bot settings using app-token auth or B2B + explicit appId

  • ethora-bot-enable-v2 — enable bot using app-token auth or B2B + explicit appId

  • ethora-bot-disable-v2 — disable bot using app-token auth or B2B + explicit appId

  • 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 for ethora-chats-message-v2

  • ethora-bot-history-v2 — compatibility alias for ethora-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)