Ethora MCP Server

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](https://github.com/dappros/ethora#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.

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/ ). 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/

or the open endpoint plus a Bearer header

claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp --header "Authorization: Bearer "

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

{

"mcpServers": { "ethora": { "url": "https://mcp.chat.ethora.com/mcp", "headers": { "Authorization": "Bearer " } } } }

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; 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: /.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