Step by step
Get a key
In the Ethora web app open Account, AI Assistants, create an API key and copy the Claude Code one-liner it shows. Or skip the browser: add the open endpoint with no key, then ask Claude Code to call ethora-user-register or ethora-user-login { createApiKey: true }; the result includes a key and connectorUrl, shown once.
Add the server
Two equivalent forms: key in the path, or the open endpoint with a Bearer header.
# 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>"
Pick a scope
The default scope is local: stored in ~/.claude.json for the current project only. --scope user loads it in all your projects. --scope project writes .mcp.json at the project root for version control, so keep personal keys out of it: use the open /mcp endpoint and let each developer log in inside the session. Claude Code prompts before using project-scoped servers.
# global for you, every project claude mcp add --transport http ethora --scope user https://mcp.chat.ethora.com/mcp/k/<your API key> # shared with the team, no secret in the repo claude mcp add --transport http ethora --scope project https://mcp.chat.ethora.com/mcp
Verify
claude mcp list prints every server with its health; claude mcp get ethora shows details. Inside a session /mcp shows status, authenticates OAuth servers, toggles, clears authentication or reconnects. Then ask for ethora-status: authMode: user and hosted: true mean you are set.
claude mcp list # ethora should show as connected claude mcp get ethora # inside a session: /mcp
A worked terminal session
Start Claude Code in your project and describe the app. It provisions through the MCP tools and can write the integration in the same turn: ethora-widget-embed-snippet for the website widget, ethora-generate-chat-component-app-tsx for a chat component App.tsx.
$ claude > Create an Ethora app called Support Desk with a room called Tickets, create a triage agent, invite it to the room, post “My invoice is wrong” and show the reply. Then give me the widget script tag for our site. # calls, in order: ethora-app-create, ethora-app-select, ethora-app-create-chat, # ethora-agents-create-v2, ethora-agent-invite-to-chat, ethora-chats-message-v2, # ethora-agents-activate-v2, ethora-widget-embed-snippet
stdio for CI and scripted runs
Where a job cannot hold a personal key, run the local package with an app JWT from environment variables. In claude -p runs project-scoped servers load without prompting. Same tools; app deletion is off unless ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true.
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
# or start it directly for another stdio client
ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-serverThe 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 |
| Generate Chat Component App.tsx | ethora-generate-chat-component-app-tsx | Generate a ready-to-paste React App.tsx snippet that mounts @ethora/chat-component. | read-only |
A worked example
“Create an Ethora app called Support Desk with a room called Tickets, create a triage agent and invite it, post "My invoice is wrong" and show the reply, then generate the App.tsx that mounts the chat component for that room.”
ethora-app-create{ displayName: "Support Desk" }ethora-app-select{ appId }ethora-app-create-chat{ title: "Tickets" }ethora-agents-create-v2{ name: "Triage", prompt: "You triage support questions..." }ethora-agent-invite-to-chat{ agentIdOrAddress, chatJid }ethora-chats-message-v2{ text: "My invoice is wrong", roomJid, waitForReplySec: 45 }ethora-generate-chat-component-app-tsx{ roomJid }
A provisioned app with a live triage agent, the reply in the terminal, and a ready-to-paste App.tsx.
Good to know
claude mcp remove ethoraunregisters the server; revoke the key separately withethora-api-key-revoke.- The key acts as you and lives in
~/.claude.jsonfor local and user scope; keep that file off shared machines. ethora-help { goal }returns recipes such aswidget,sources-ingestandchat-test;ethora-run-recipeexecutes one.- A 406 from the endpoint means the client did not accept both
application/jsonandtext/event-stream.
