Step by step
Method 1: an API key
An API key is a revocable user token. Create one under Account, AI Assistants, or with ethora-api-key-create { name?, ttlDays? }: default 90 days, maximum 365, shown once with a connectorUrl. Send it as a Bearer header on the open endpoint, or use the path form for connectors. Keys carry no scope claim and get full access.
# header form, any client that sends headers POST https://mcp.chat.ethora.com/mcp Authorization: Bearer <your API key> # path form, for Claude.ai and ChatGPT connectors https://mcp.chat.ethora.com/mcp/k/<your API key>
Method 2: log in or register inside the session
Connect to /mcp with no credentials. ethora-user-login { email, password } binds an existing account; add createApiKey: true for a key to reuse. ethora-user-register { email, firstName, lastName } creates an account, logs the session in and returns a generated password, an API key and connectorUrl once: no browser, no email confirmation. This is how an agent gets its own identity.
1. connect https://mcp.chat.ethora.com/mcp
2. call ethora-user-register { email, firstName, lastName }
3. store apiKey and connectorUrl from the result
4. next time, reconnect with Authorization: Bearer <apiKey>Method 3: OAuth 2.1
The authorization server is the Ethora API at https://api.chat.ethora.com: dynamic client registration, PKCE, scopes read, write and admin. The MCP server publishes RFC 9728 protected-resource metadata, and an unauthenticated request to /mcp/oauth gets 401 with a WWW-Authenticate header pointing at it. Users disconnect grants under Account, AI Assistants, Connected AI apps.
https://mcp.chat.ethora.com/mcp/oauth
# metadata: /.well-known/oauth-protected-resource/mcp/oauthScopes per tool
On /mcp/oauth the token’s scope is checked per call: read-only tools need read, the 12 destructive tools admin, everything else write. search, fetch, ethora-help, ethora-status and ethora-doctor need no scope. The identity tools (login, register, configure, ethora-api-key-*) are hidden because the token already fixes who you are. A grant lacking a scope gets INSUFFICIENT_SCOPE (403); reconnect and approve the wider scope.
Key lifecycle
ethora-api-key-list shows id, name, created and expiry, never the value. ethora-api-key-revoke { id } is immediate: the next request fails with REFRESH_RECORD_NOT_FOUND. Rotate by creating a new key, updating the client, then revoking the old. The server never logs request URLs or tokens.
Sessions and the stdio server
Each MCP session holds private in-memory state (login, selected app, tokens); nothing is shared between sessions. Stay in user auth mode on the hosted server: ethora-status shows authMode: user. The stdio server takes ETHORA_APP_JWT and optional ETHORA_B2B_TOKEN from the environment, or ethora-configure at runtime.
ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-server
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 |
|---|---|---|---|
| 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 |
| 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 |
| Connection Doctor | ethora-doctor | Diagnose the session: validate the config is internally consistent for the active auth mode and ping the Ethora API (GET /v1/ping). | 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 |
| Use User Auth | ethora-auth-use-user | Switch this session’s active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. | write |
| Configure Connection | ethora-configure | Set the Ethora API URL and credentials for this MCP session. | write |
A worked example
“Register an Ethora account for [email protected] as Ops Agent, keep the API key for later, then list my apps and tell me how the session is authenticated.”
ethora-user-register{ email: "[email protected]", firstName: "Ops", lastName: "Agent" }ethora-status{}ethora-app-list{}ethora-api-key-list{}
An account bound to the session, a stored API key and connector URL, an empty app list and a status showing authMode: user.
Good to know
- Self-hosted: the same server ships with the Ethora monoserver deploy (
services.mcp.enabledindeploy.yml), served atmcp.<your domain>/mcpwith the same entry points and OAuth; agent traffic never leaves your infrastructure. - Error codes:
TOKEN_MISSING(401) no user token in the session;REFRESH_RECORD_NOT_FOUND(401) key revoked;INSUFFICIENT_SCOPE(403) OAuth grant too narrow;AUTH_USER_REQUIREDwrong auth mode, fix withethora-auth-use-user. - A key acts as the user until revoked; keep it in the client’s secret store, not in a committed
mcp.json.
