Ethora MCP Server (Model Context Protocol)

Add the hosted server in one click. You sign in through your browser; there is nothing to install and no key to paste.

For Claude.ai, ChatGPT, Claude Desktop, LM Studio and anything else that takes a connector URL, add https://mcp.chat.ethora.com/mcp/oauth and sign in. Running it yourself instead? See Using with stdio clients.

The MCP server for Ethora, an open-source chat and messaging platform with a built-in AI agent framework. It lets Claude, ChatGPT, Cursor, Claude Code, VS Code and autonomous agents create Ethora apps, chat rooms, users and AI agents, post messages, index RAG sources and produce website chat-widget embeds, all through tool calls.

Part of the Ethora SDK ecosystem. Cross-SDK updates: Release Notes. Package changes: CHANGELOG.md.

• npm: https://www.npmjs.com/package/@ethora/mcp-server
• MCP Registry: io.github.dappros/ethora-mcp-server (https://registry.modelcontextprotocol.io/)
• Ethora API (Swagger): https://api.chat.ethora.com/api-docs/#/

Three ways to use it

The hosted and self-hosted modes are the same server started with ETHORA_MCP_TRANSPORT=http. Every MCP session has private in-memory state: one client's login, selected app or tokens are never visible to another session.

60-second quickstart

Claude.ai or ChatGPT (custom connector). In the Ethora web app open Account, then the AI Assistants tab, create an API key and copy the personal connector URL it shows (https://mcp.chat.ethora.com/mcp/k/<key>). Paste it as a custom connector. Every conversation is authenticated with no login step. For a listed connector that uses the vendor's OAuth login instead, the URL is https://mcp.chat.ethora.com/mcp/oauth.

Claude Code.

# with a personal connector URL (no headers needed)
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp/k/<your API key>

# or the open endpoint plus a Bearer header
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp --header "Authorization: Bearer <your API key>"

Cursor, VS Code, and any client that takes a URL and headers.

{
  "mcpServers": {
    "ethora": {
      "url": "https://mcp.chat.ethora.com/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}

Autonomous agents with no account yet. Connect to https://mcp.chat.ethora.com/mcp with no credentials and call ethora-user-register with an email, first and last name. It creates the account, logs the session in, and returns a generated password plus an API key and connectorUrl exactly once. Store the key and reconnect later with the Bearer header or the personal URL; nothing else is needed, no browser and no email confirmation.

stdio CLI.

ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-server

Then ask your agent to call ethora-status, ethora-user-login (or ethora-user-register) and ethora-app-list. Lost at any point, call ethora-help: it reads the current state and returns the recommended next calls.

Entry points and authentication

Stay in user auth mode on the hosted server (ethora-status shows authMode: user). App-token and B2B modes exist for server integrations; the agents and rooms routes reject app tokens.

API keys

• ethora-api-key-create { name?, ttlDays? } mints a key (default 90 days, max 365), shown once together with connectorUrl. ethora-user-register mints one by default and ethora-user-login { createApiKey: true } on request.
• ethora-api-key-list shows id, name, created and expiry, never the value. ethora-api-key-revoke { id } invalidates it immediately: the next request with that key fails with REFRESH_RECORD_NOT_FOUND.
• The same keys are managed in the Ethora web app under Account, AI Assistants, where the personal URL, a Claude Code one-liner and a Cursor config are shown with copy buttons.
• A key acts as the user. Treat the personal URL like a password: do not share screenshots of it, revoke it if it leaks. The server never logs request URLs, and the monoserver nginx template logs method and status only on the MCP host.

OAuth 2.1 (/mcp/oauth)

Set ETHORA_MCP_AUTH_ISSUER to the public URL of the Ethora API that hosts the authorization server (the monoserver deploy sets it). The MCP server then:

• serves RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp/oauth, naming the authorization server and the three scopes;
• answers unauthenticated requests on /mcp/oauth with 401 and WWW-Authenticate: Bearer resource_metadata="...", which is how clients discover the flow;
• validates each token against the API once per session (cached five minutes) and enforces the token's scope per tool: read-only tools need read, destructive tools need admin, everything else needs write. search, fetch, ethora-help, ethora-status and ethora-doctor need no scope. Tokens without a scope claim (API keys) get full access;
• hides the identity tools (ethora-user-login, ethora-user-register, ethora-session-configure, ethora-auth-mode-set, ethora-auth-mode-set, ethora-api-key-create, ethora-api-key-list, ethora-api-key-revoke) because the token already fixes who you are.

The authorization server itself is part of the Ethora backend: <issuer>/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize (a consent page with sign-in, account creation and Google sign-in), /oauth/token, /oauth/revoke and /oauth/userinfo. Users see and disconnect OAuth grants under Account, AI Assistants, Connected AI apps. When ETHORA_MCP_AUTH_ISSUER is unset, both OAuth routes return 404 and discovery omits them.

Identity scopes. Some directories (ChatGPT) require the minimal OpenID Connect surface on top of OAuth 2.1: the openid and email scopes and a userinfo endpoint that returns sub, email and email_verified. These scopes grant no access to apps or data; they only let the client see who signed in, and the consent page says so in plain words. There are no ID tokens or JWKS, because nothing consumes them.

Email confirmation is optional. Ethora never blocks sign-up or the dashboard on a confirmed address. When a client asks for the identity scopes and the account's address is not yet confirmed, the consent page adds one step: send the confirmation link, continue after confirming, or continue without sharing the address (the identity scopes are dropped from the grant and everything else proceeds). Google sign-ins arrive confirmed and skip the step. The same confirmation can be sent from Account, AI Assistants in the web app.

What agents can do

The end-to-end journey a new user typically asks for, with the tools in order:

1. ethora-user-register (or ethora-user-login) to get an authenticated session and an API key.
2. ethora-app-create { displayName } then ethora-app-select { appId } to make the new app current.
3. ethora-chat-create { title } to create a group room. The result contains the room JID ${appId}_${chatId}; every room tool accepts the JID or the bare chatId.
4. ethora-agent-create { name, prompt, ... } to create an AI agent persona in that app.
5. ethora-agent-invite { agentIdOrAddress, chatJid } to put the agent in the room. A bot instance is spawned live, no restart needed.
6. ethora-message-send { text, roomJid, waitForReplySec: 45 } to post a message and wait for the agent's answer, returned as replies. ethora-chat-history reads the room afterwards.
7. ethora-agent-activate { agentId, chatJid } to make that agent the app's default responder, then ethora-widget-snippet-get for the <script> tag that puts the AI chat widget on a website.

ethora-help { goal } returns this and the other recipes (user-login, broadcast, sources-ingest, files-upload, bot-manage, chat-test, widget, b2b-bootstrap-ai) with the calls filled in for the current state, and ethora-recipe-run executes them.

First-minute conventions

• Every create tool answers the same way. ethora-app-create, ethora-chat-create, ethora-agent-create return the raw API object plus created (kind, id, name, and jid or address where relevant) and next, two to four suggested calls with arguments filled in. ethora-app-create also returns dashboardUrl, the app in the web dashboard.
• ethora-help { goal } has a recipe for each headline job: new-app, in-app-chat, multi-agent-room, widget, chat-test, plus the server-integration goals. Each returns the calls in order with arguments to copy.
• Who spoke. ethora-message-send replies and ethora-chat-history rows carry senderName and senderKind (human, agent, app), so a multi-agent room reads as "Freud: ..., Jung: ..." rather than instance ids.
• Search understands intent. search maps the phrases people use ("add chat to my React app", "several agents talking to each other", "webhook when a message arrives") to the documents that answer them, and doc:not-available says plainly what is not exposed over MCP and where it lives instead. Whole documents are fetchable by their bare id (doc:recipes, doc:chat-component-quickstart, doc:sdk-backend-quickstart, doc:auth-map).

Documentation inside the server

• instructions in the initialize result tell the assistant how identity works on the entry point it connected through: the open endpoint explains login and register, personal-URL and Bearer sessions are told they are already authenticated and must never ask for a password or key, OAuth sessions the same plus how to react to INSUFFICIENT_SCOPE.
• search { query } and fetch { id } (the ChatGPT connector convention) search an in-memory corpus: the auth map, quickstarts, recipes, a hosted getting-started guide, an API keys guide and one reference entry per tool with its inputs. They work unauthenticated.
• Resources ethora://docs/auth-map, ethora://docs/chat-component/quickstart, ethora://docs/sdk-backend/quickstart, ethora://docs/recipes and prompts ethora-auth-map, ethora-vite-quickstart, ethora-nextjs-quickstart, ethora-backend-sdk-quickstart, ethora-recipes, ethora-agents-quickstart.

Tool groups

A session lists the core group only at first: 24 tools covering the whole "sign in, create an app, add rooms and messages, create and activate an agent, give it a knowledge base, get the widget" journey, one variant per operation. The other groups are registered but hidden, which keeps tools/list around 40 KB instead of 120 KB and gives assistants a short list to choose from.

Three ways to get more:

• ethora-tools-enable { group } enables a group for the session (or { group: "all" }); the server sends tools/list_changed and the client refreshes. With no arguments it returns the catalogue with counts.
• Calling a hidden tool by name enables its group and runs it, so a name learned from the docs or an earlier session is never refused.
• ?tools=all on the endpoint URL (hosted) or ETHORA_MCP_TOOLS=all (stdio) lists everything up front.

search and fetch describe hidden tools too; every tool doc names its group, and doc:tool-groups is the catalogue. Legacy and async variants carry a first line naming the preferred sibling.

App deletion and bulk-delete tools are only registered when ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true (the monoserver deploy sets it; the stdio default is off). Alias tools (ethora.b2b.*, ethora-bot-message-send, ethora-bot-history) are off by default (ETHORA_MCP_ENABLE_ALIASES=true to expose them); the canonical tools cover the same ground.

Website widget

ethora-widget-snippet-get returns the tag for the embeddable AI chat widget:

<script id="chat-content-assistant" src="https://widget.<your domain>/assistant.js"
  data-app-id="<appId>" data-api-base="https://api.<your domain>" data-bot-name="Helper" defer></script>

The widget answers with the app's active bot (defaultBotInstanceId). On an app created through the API run ethora-agent-create, ethora-chat-create, ethora-agent-invite and ethora-agent-activate { agentId, chatJid } first; the tool lists these prerequisites and ethora-help { goal: "widget" } walks through them. Activation runs in user auth by setting the app's default bot instance (what the admin AI Widget dropdown does). Until a bot is active, the widget's session endpoint answers AI_BOT_NOT_CONFIGURED. ethora-chat-component-app-generate produces a React App.tsx for @ethora/chat-component instead.

Configuration

Env vars (stdio and hosted)

Hosted mode only

A .env file in the working directory is loaded at startup; real environment variables win. Credentials can also be set per session with ethora-session-configure (in memory only; on a hosted server apiUrl cannot be changed).

Endpoints (hosted)

Response envelope

Every tool returns JSON text in one shape: success { ok: true, ts, meta, data }, failure { ok: false, ts, meta, error } where error carries code (the API's own code when it has one), message, httpStatus, requestId and a one-line hint.

Using with stdio clients

Every stdio client runs npx -y @ethora/mcp-server; pass credentials as env vars (preferred) or call ethora-session-configure for a quick local test (its arguments end up in the transcript). For hosted mode use the one-click buttons at the top of this README, or the URL form in the quickstart. One-click buttons for the stdio package:

Cursor

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

VS Code (and GitHub Copilot agent mode)

.vscode/mcp.json (note the key is servers):

{ "servers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Claude Code

claude mcp add ethora -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" -- npx -y @ethora/mcp-server

Add --scope user to make it available in every project; verify with claude mcp list.

Claude Desktop

Settings, Developer, Edit Config (claude_desktop_config.json):

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Gemini CLI, Windsurf, Cline

Same mcpServers block as above in ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json or cline_mcp_settings.json.

Codex CLI

~/.codex/config.toml (the table is mcp_servers with an underscore):

[mcp_servers.ethora]
command = "npx"
args = ["-y", "@ethora/mcp-server"]

Container

docker build -t ethora-mcp-server .
docker run -i --rm -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" ethora-mcp-server

Add -e ETHORA_MCP_TRANSPORT=http -e ETHORA_MCP_HTTP_HOST=0.0.0.0 -p 3030:3030 to run the hosted mode in a container.

B2B provisioning (server integrations)

With ETHORA_B2B_TOKEN configured, ethora-auth-mode-set switches the session to tenant-actor auth and ethora-b2b-app-bootstrap-ai creates an app, indexes sources (crawlUrl, docs[] as base64) and configures its bot in one call, with optional llmProvider and llmModel. ethora-b2b-app-provision adds app tokens and default rooms. ethora-user-batch-create plus ethora-user-batch-job-wait provision users asynchronously and ethora-broadcast-send plus ethora-broadcast-job-wait send a message to many rooms. ethora-b2b-runbook-generate prints the call order for your own automation.

Troubleshooting

Feedback

ethora-feedback-submit sends a report (bug, unexpected, feature, docs, other) to the Ethora team from inside a session. The point of doing this over MCP rather than a web form is context: the session's last few tool failures travel with the report - tool name, error code and the API requestId - so a report can be joined to the server-side log entry instead of being re-typed from memory. Set includeRecentErrors: false when the report is unrelated to a failure.

It works whether or not the session is authenticated, because the reporter we most need to hear from is the one whose sign-up or credential is the thing that broke; an authenticated report is attributed to that account, and an anonymous one may carry an email for a reply. It is also exempt from OAuth scope enforcement, so a read-only grant can still report a problem.

Credential-shaped keys in the attached context are redacted before sending. That is key-based, so it cannot catch a credential pasted into the free-text message: the tool description tells the model not to put secrets or end-user personal data there.

Delivery is configured on the API side (FEEDBACK_EMAIL_TO, FEEDBACK_SLACK_WEBHOOK_URL, FEEDBACK_RETENTION_DAYS); the MCP server only submits.

Usage attribution

Outbound API calls carry X-Ethora-Client: mcp/<version> and, for the duration of a tool call, X-Ethora-Tool: <tool-name>. The API records these on its request log as client and source: mcp:<tool>, which is how MCP traffic is separated from the web app and counted per tool. The public unauthenticated endpoints (/ping, /apps/get-config) are left unattributed.

Security notes

• Credentials are redacted from tool results. appSecret, tenantSecret, appToken, passwords and similar keys come back as [redacted] from every tool (results enter the model's context and client logs). ethora-app-credentials-reveal { appId, confirm: true } reveals an app's appToken on purpose and needs the admin scope over OAuth; the App Secret is only ever shown in the web dashboard API tab. Login, register and the api-key / app-token minting tools still return their credential once by design.

• API keys and personal URLs act as the user until revoked. Keep them in your client's secret store, never in shared config or screenshots, and revoke on suspicion.

• The server never logs request URLs or tokens. Keep your reverse proxy's access log free of request paths for the MCP host (the monoserver nginx template does).

• Anything returned by a tool is visible to the model and stored in the conversation transcript; the server tells assistants not to print keys or passwords, and to confirm destructive tools with the user.

• This repo runs report-only secret and SAST scans (gitleaks, semgrep) on pushes and PRs.

Development

Version numbers

Versions are calendar-based: YY.M.patch, where YY.M is the year and month the release ships (26.9.5 is the fifth September 2026 release, 26.10.0 the first of October) and patch counts releases within the month. No leading zero on the month, so 26.10 sorts after 26.9 under semver. Breaking changes do not bump a major; they get the next patch and a changelog entry, and earlier tool names stay callable as aliases. npm run sync-version refuses any other shape or any month other than the current one (ETHORA_VERSION_MONTH=YY.M overrides on purpose), and the publish workflow runs it. 27.0.0 and 27.1.0, published on 2026-09-24 against this rule, are deprecated; 26.9.5 is the same code.

Tool naming

Since 27.0 every listed tool follows one rule: ethora-<resource>-<verb>[-<qualifier>].

• resource is a singular noun, one or two words: app, agent, chat, message, broadcast, source-site, source-doc, user, file, bot, api-key, app-token, widget, wallet, session, auth-mode, recipe, tools.
• verb is the last word: create, list, get, update, delete, send, set, run, reveal, upload, crawl, reindex, start, wait, enable, disable, generate.
• a qualifier only ever follows the verb: -wait (blocking form of an async job), -batch, -legacy, -b2b.
• no API-version suffixes: -v2 is gone from every name. search and fetch keep their names by ChatGPT connector convention.

Every earlier name still works. Old names are aliases: never listed by tools/list, but a call to one is rewritten to the canonical tool (with a preset argument where three or two tools became one, such as ethora-auth-use-app becoming ethora-auth-mode-set { mode: "app" }), so published configs, recipes and saved conversations keep working. Results and usage attribution name the canonical tool. The full mapping is in the alias table at the end of this file and in src/toolNames.ts, which the test suite checks against the registry.

Related repos

• ethora-chat-component: the React chat component used in widgets and stand-alone apps
• ethora-monoserver: deploy automation that ships this server as an optional service (private repository, available to enterprise customers)
• ethora-wp-plugin: WordPress integration
• rag_demos: RAG AI assistant examples

Quality and maintenance score

Independently inspected by Glama, which builds the server, catalogues its tools and rates tool-definition quality and maintenance activity.

Earlier tool names

Names used before 27.0 and the tool each one now resolves to. All of them remain callable.

License

See LICENSE.