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

	Where it runs	Best for
Hosted (Ethora Cloud)	https://mcp.chat.ethora.com/mcp (production; https://mcp.chat-qa.ethora.com/mcp is the QA instance)	Claude.ai, ChatGPT, Claude Code, Cursor and agents that talk to Ethora Cloud with no local install
Self-hosted	Ships with the Ethora monoserver deploy; enable services.mcp.enabled in deploy.yml and it is served at mcp.<your domain>/mcp	Dedicated or on-premise Ethora installs; agent traffic never leaves your infrastructure
stdio CLI	npx -y @ethora/mcp-server on your machine, configured with env vars	Local development, CI, and clients that launch a command

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.

Account memory. Some clients open a new MCP session for every tool call (ChatGPT does), which would lose the selected app between calls. So the server keeps a small snapshot per signed-in account, keyed by the user id in the bearer token: the current app and agent, the appToken the API handed that account for the current app, and the enabled tool groups. A new session that arrives with a token for the same account (OAuth, personal URL or Bearer header) gets it back, after the token has been validated against the API. Memory lives in the process, expires after 24 hours idle, and never holds the user token itself. Two more defaults close the same gap: ethora-app-create selects the new app, and an account that owns exactly one app has it selected automatically on the first app-scoped call.

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

Entry point	Who supplies identity	Typical client
/mcp (add ?tools=all to list every tool up front)	Nobody at connect time. Call ethora-user-login or ethora-user-register inside the session, or send Authorization: Bearer <token> on every request (user API key, app token or B2B token; the server picks the auth mode from the token type)	Agents, Claude Code, Cursor, connectors added as "no auth"
/mcp/k/<api-key>	The key in the path, applied like a Bearer header	Claude.ai and ChatGPT custom connectors, which take a URL but no headers
/mcp/oauth	An OAuth 2.1 access token obtained through the Ethora authorization server (dynamic client registration, PKCE, access scopes read, write, admin, plus the identity scopes openid and email for directories that require them)	Connector directories (Claude, ChatGPT); vendors run the login flow themselves
stdio	Env vars ETHORA_APP_JWT (login/register bootstrap) and optional ETHORA_B2B_TOKEN, or ethora-session-configure at runtime	Local CLI

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; deleting, revoking and rotating (and revealing a credential) need admin; everything else, including updates that overwrite fields and are therefore marked destructive, 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.

Group	What it covers	Tools
core (listed by default)	Sign in or register, create an app, add rooms and messages, create and activate an AI agent, give it a knowledge base, get the website widget. Always listed.	ethora-status, ethora-help, ethora-feedback-submit, ethora-tools-enable, search, fetch, ethora-user-register, ethora-user-login, ethora-api-key-create, ethora-app-create, ethora-app-list, ethora-app-select, ethora-app-update, ethora-chat-create, ethora-message-send, ethora-chat-history, ethora-agent-create, ethora-agent-list, ethora-agent-update, ethora-agent-invite, ethora-agent-activate, ethora-source-site-crawl-wait, ethora-source-doc-upload, ethora-widget-snippet-get
keys	List and revoke API keys, reveal an app's credentials, mint and rotate app tokens.	ethora-api-key-list, ethora-api-key-revoke, ethora-app-credentials-reveal, ethora-app-token-create, ethora-app-token-list, ethora-app-token-revoke, ethora-app-token-rotate
session	Diagnostics, recipes and switching the session's auth mode (app token, B2B token) for server integrations.	ethora-doctor, ethora-recipe-run, ethora-session-configure, ethora-auth-mode-set, ethora-auth-mode-set, ethora-auth-mode-set
apps-admin	Delete, export and import whole apps; inspect default rooms.	ethora-app-delete, ethora-app-export, ethora-app-import, ethora-app-rooms-list, ethora-app-rooms-list
rooms	Delete rooms, broadcast to many rooms, search messages, read message context and unread counts.	ethora-chat-delete, ethora-broadcast-send, ethora-broadcast-job-start, ethora-broadcast-job-wait, ethora-message-search, ethora-message-context, ethora-chat-unread-counts
agents-admin	Inspect, clone (with or without its knowledge), delete, export and import agents; try an agent without a room; check and rebuild its knowledge index; edit its Memory and visibility.	ethora-agent-get, ethora-agent-clone, ethora-agent-delete, ethora-agent-export, ethora-agent-import, ethora-agent-visibility-set, ethora-agent-soul-set, ethora-agent-soul-append, ethora-agent-try, ethora-agent-knowledge-get, ethora-agent-knowledge-rebuild
sources	Knowledge-base maintenance: async crawl and reindex jobs, stop a crawl, list and tag sites and documents, delete URLs and documents.	ethora-source-site-crawl, ethora-source-site-crawl-cancel, ethora-source-site-reindex, ethora-source-site-reindex-wait, ethora-source-site-list, ethora-source-site-tags-update, ethora-source-site-url-delete, ethora-source-site-url-delete-batch, ethora-source-doc-list, ethora-source-doc-tags-update, ethora-source-doc-delete
widget	Read and change the website widget's saved look (colours, fonts, size, launcher, teaser, texts); live embeds pick it up without a new snippet.	ethora-widget-appearance-get, ethora-widget-appearance-set
users-files	Batch-create users and upload, fetch or delete files.	ethora-user-batch-create, ethora-user-batch-job-start, ethora-user-batch-job-wait, ethora-file-upload, ethora-file-get, ethora-file-delete
legacy-bot	The per-app bot of apps created in the dashboard before the agents framework, and the pre-v2 document tools. Prefer the agents and sources tools for anything new.	ethora-bot-get, ethora-bot-update, ethora-bot-enable, ethora-bot-disable, ethora-bot-widget-get, ethora-bot-history, ethora-bot-message-send, ethora-bot-instance-list, ethora-bot-instance-status-set, ethora-bot-instance-diagnose, ethora-bot-instance-leave, ethora-bot-instance-test, ethora-bot-enable-b2b, ethora-source-doc-upload-legacy, ethora-source-doc-delete-legacy
b2b	Server-to-server provisioning with a B2B token, plus code and config generators for integrations.	ethora-b2b-app-create, ethora-b2b-app-provision, ethora-b2b-app-bootstrap-ai, ethora-b2b-runbook-generate, ethora-env-examples-generate, ethora-chat-component-app-generate, ethora.b2b.auth.use, ethora.b2b.app.create, ethora.b2b.bot.enable, ethora.b2b.broadcast.wait, ethora.b2b.app.bootstrap-ai
wallet	Wallet balance and ERC-20 transfer. Local (stdio) only; never offered on the hosted server.	ethora-wallet-balance-get, ethora-wallet-erc20-transfer

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>" defer></script>

The widget's look (colours, fonts, size, launcher, teaser bubble, texts) is saved on the app: ethora-widget-appearance-set { appearance: { "data-primary-color": "#7c3aed" } } (the widget group), the same setting as App settings > AI Widget in the admin panel. Every embed loads it when it opens, so later changes reach live sites without a new snippet. A data-* attribute written on the tag wins over the saved value on that site.

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)

Variable	Meaning
ETHORA_API_URL	Full API URL, e.g. https://api.chat.ethora.com/v1 (default). On a hosted server it is fixed for all sessions
ETHORA_BASE_URL	Host-only alternative to ETHORA_API_URL; /v1 is appended
ETHORA_APP_JWT	App JWT used only by login and register (ETHORA_APP_TOKEN is a legacy alias)
ETHORA_APP_DOMAIN_NAME	Base app domainName; when ETHORA_APP_JWT is empty the server fetches the app JWT from GET /v1/apps/get-config?domainName=... at startup
ETHORA_B2B_TOKEN	B2B server token for x-custom-token tenant-actor routes
ETHORA_MCP_TOOLS	all lists every tool from the start instead of the core group (stdio; hosted uses ?tools=all on the URL)
ETHORA_MCP_ENABLE_DANGEROUS_TOOLS	true registers app deletion, wallet transfer and bulk-delete tools (default off)
ETHORA_MCP_OPENAI_APPS_CHALLENGE	Hosted only. Token issued by the OpenAI apps portal for domain verification; served verbatim at /.well-known/openai-apps-challenge (404 when unset)
ETHORA_MCP_ENABLE_ALIASES	true exposes the dot-namespaced alias tools (default off)

Hosted mode only