Step by step
Get a personal connector URL
Sign in to the Ethora web app, open Account, then the AI Assistants tab, and create an API key. The page shows the personal connector URL with a copy button. The value is shown once; keys last 90 days by default, up to 365. Treat the URL like a password. No account yet? Register, or let an agent do it (see authentication).
https://mcp.chat.ethora.com/mcp/k/<your API key>
Add it in Claude.ai
On Pro and Max plans open Customize, then Connectors, click the plus button and choose Add custom connector. Name it Ethora and paste the personal URL; no separate sign-in is needed. On Team and Enterprise plans an Owner adds it under Organization settings, Connectors, Add, then Custom, Web, and members connect it from Customize, Connectors. Free plans allow one custom connector.
Or use the OAuth endpoint
If you prefer a login flow over a pasted key, add the OAuth endpoint. Claude discovers the Ethora authorization server from the 401 response, registers itself, runs PKCE and asks you to sign in and approve the scopes read, write and admin. A listed connector uses this endpoint too.
https://mcp.chat.ethora.com/mcp/oauth
Use it in Claude Desktop
Claude Desktop takes remote servers through the same Connectors settings: open Settings, Connectors and add the personal URL as a custom connector. To run the server locally instead, use Settings, Developer, Edit Config and add the stdio block to claude_desktop_config.json, with credentials from environment variables or ethora-configure.
{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }Ask, then approve what matters
Enable the Ethora connector for the conversation and ask in plain language. When unsure of the order of calls Claude runs ethora-help, which returns the recommended next tools. Twelve tools carry destructiveHint (deleting apps, rooms, files, documents or agents, revoking keys, rotating app tokens): Claude asks before each. Pick Allow always only when you are confident about the action.
Disconnect or revoke
In Claude open Customize, Connectors, find Ethora and click Remove (or the three dots menu). From the Ethora side, run ethora-api-key-revoke or revoke the key under Account, AI Assistants; the next request fails with REFRESH_RECORD_NOT_FOUND. OAuth grants are disconnected under Account, AI Assistants, Connected AI apps.
The tools this uses
Names and descriptions come from the server’s own tool list. Read-only tools are safe to auto-approve; destructive ones make your client ask first. Full reference.
| Tool | Name | What it does | Access |
|---|---|---|---|
| Session Status | ethora-status | Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present (booleans like hasAppJwt - values never echoed),... | read-only |
| Help and Next Steps | ethora-help | Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends next tool calls + recipes based on current... | read-only |
| Register Account | ethora-user-register | Create a new Ethora user account by email + first/last name, then log in and bind the session. | write |
| Log In | ethora-user-login | Authenticate as an existing Ethora user with email + password. | write |
| Create API Key | ethora-api-key-create | Mint a long-lived, revocable API key for the currently logged-in user. | write |
| List API Keys | ethora-api-key-list | List the current user’s API keys (id, name, createdAt, expiresAt). | read-only |
| Revoke API Key | ethora-api-key-revoke | Revoke one of the current user’s API keys by id. | destructive |
| List Apps | ethora-app-list | List all Ethora apps (tenants) owned by the currently logged-in user. | read-only |
| Create App | ethora-app-create | Create a new Ethora app (tenant) owned by the currently logged-in user. | write |
| Create Chat Room | ethora-app-create-chat | Create a new chat room (MUC room) inside an app the caller owns. | write |
A worked example
“Create an Ethora app called Clinic Desk, add a room called Front desk, create a friendly receptionist agent, put it in the room and send it a test message asking about Saturday opening hours.”
ethora-app-create{ displayName: "Clinic Desk" }ethora-app-select{ appId }ethora-app-create-chat{ title: "Front desk" }ethora-agents-create-v2{ name: "Receptionist", prompt: "You are the friendly front desk of Clinic Desk..." }ethora-agent-invite-to-chat{ agentIdOrAddress, chatJid }ethora-chats-message-v2{ text: "Are you open on Saturdays?", roomJid, waitForReplySec: 45 }
A new app with one room, a live AI agent in it and the agent reply returned in the replies field, without leaving Claude.
Good to know
- Connectors take a URL but no headers, so Claude uses the
/mcp/k/<key>form rather than a Bearer header. - Each MCP session keeps private state (login, selected app), so a new conversation starts clean; the key in the URL keeps you authenticated.
- Anything a tool returns is stored in the conversation; the server tells assistants not to print keys or passwords.
- Lost a key? It cannot be read back; create a new one and revoke the old.
