Setup

Connecting the Encelade MCP server takes three steps: add the connector, authorize in your browser, and verify. Claude Desktop, Claude Code, and Codex connect over OAuth, so there is no API token to create — you only need one for header-based setups.

Prefer a screenshot-led walkthrough? See the Connect Claude to Encelade tutorial.

Quick setup

Add the connector

Open Settings → Integrations → Add custom connector.
Enter:
- Name: Encelade
- Remote MCP server URL: https://www.encelade.ai/api/mcp
Leave the Advanced settings (manual OAuth fields) empty — Claude Desktop will auto-discover them.
Click Add.

claude mcp add encelade \
  --transport http \
  https://www.encelade.ai/api/mcp

If a browser window doesn't open automatically, run /mcp inside Claude Code, select encelade, then choose authenticate.

codex mcp add encelade \
  --url https://www.encelade.ai/api/mcp

Authorize

A browser window opens at the Encelade authorization page. Sign in if prompted, check that the client name and redirect host match the client you just added, pick the workspace to connect (you need to be an admin or editor there), and click Authorize. You'll be redirected back to your client automatically.

Under the hood: the server answers the first request with 401 and a WWW-Authenticate header. Your client discovers the authorization server, registers itself at /api/oauth/register, sends you to /oauth/authorize, then exchanges the returned code at /api/oauth/token with PKCE (S256). The access token is bound to the workspace you picked, covers every tool, and expires after 90 days.

Discovery endpoints (useful if you're debugging the OAuth dance manually):

Purpose	Path
Protected-resource (RFC 9728)	/.well-known/oauth-protected-resource
Authorization-server (RFC 8414)	/.well-known/oauth-authorization-server
Authorization endpoint	`/oauth/authorize`
Token endpoint	`/api/oauth/token`
Dynamic client registration	`/api/oauth/register`

Verify

Claude Desktop: look for Encelade tools in the hammer menu.
Claude Code: run claude mcp list — you should see encelade ✓ connected.
Codex: run codex mcp list.

Then try a simple prompt:

"List my Encelade projects."

If a list_projects tool call returns results, you're set. If you see an authentication error, jump to Troubleshooting.

Connect with an API token

Clients that can't run the OAuth flow, and scripts or CI jobs without a browser, can send a personal API token as an Authorization: Bearer header instead.

Create an API token

Go to Settings → API tokens → Create Token. Workspace admins see this tab, as do members who have been allowed to create personal tokens; if you don't, ask a workspace admin to create a token for you. The MCP server needs these scopes:

Scope	Used by
`project:read`	`list_projects`, `get_project`
`project:write`	`update_project`
`project:delete`	`delete_project`
`project:plan`	`plan_project`, `generate_project`
`project:generate`	`generate_project`, `get_generation_session` (fallback)
`session:read`	`get_generation_session`

Grant only the scopes you need. A read-only token is fine if you only want browsing.

Copy the token immediately — it is only displayed once.

Add the connector with the token

Export the token as ENCELADE_API_TOKEN, then:

claude mcp add encelade \
  --transport http \
  https://www.encelade.ai/api/mcp \
  --header "Authorization: Bearer $ENCELADE_API_TOKEN"

codex mcp add encelade \
  --url https://www.encelade.ai/api/mcp \
  --bearer-token-env-var ENCELADE_API_TOKEN

Revoking access

Each authorized client shows up in Settings → API tokens as OAuth via client name; a workspace admin can revoke it there. A revoked or expired token fails the next tool call with 401 Unauthorized; re-run the authorize step from the client to reconnect (see Troubleshooting).

Each account can hold five active OAuth connections at a time; revoke one before authorizing another client.

To rotate an API token without downtime, create the new token first, update the client's header, then revoke the old token.

What's next

Tool reference — parameters, scopes, and example prompts for all seven tools.
Troubleshooting — common errors, rate limits, and support channels.

On this page