Docs

Troubleshooting

Common MCP errors, rate limits, debugging tips, and where to get help.

Common errors

401 Unauthorized / "Authentication failed"

The Bearer token is missing, expired, revoked, or lacks the scope a tool requires.

Fix:

  1. Open Settings → API tokens and confirm the token is still active.
  2. Confirm the token has every scope listed for the tool in Tool reference — a project:read-only token cannot call update_project.
  3. Re-run the authorize step from the client. In Claude Code: /mcp → encelade → authenticate. In Claude Desktop: remove and re-add the connector.

Plan limits (402)

When the workspace is out of credits or a request is over the plan's limits, generate_project returns a structured error with a code (for example CREDITS_EXHAUSTED, PRESENTATIONS_EXHAUSTED or PAGE_LIMIT_EXCEEDED) and an upgrade_url; edit_project returns CREDITS_EXHAUSTED the same way. Branch on code rather than string-matching. For a page limit, pass fitToPageCap: true to condense the deck into the plan's page cap.

Rate limited

generate_project is capped at 10 calls per minute, and it also fails while too many runs are in progress. Calls above either limit fail until the window resets or a run finishes. Other tools follow the default public-API rate limit.

"Project not found"

Returned whenever (a) the project genuinely does not exist, (b) the calling user is not a member of the project (and not a tenant admin), or (c) the pid is malformed. The MCP server intentionally collapses these into one message to avoid leaking workspace structure.

Generation appears stuck

A run takes a few minutes. Poll get_generation_run every 5–15 seconds and watch phase and status. A run that fails ends at failed with an error of { stage, code }; start a new one with generate_project. If that also fails, contact support with both run IDs.

Validation failed: ...

Returned when your input doesn't satisfy the tool's parameter schema (e.g., brief is empty, pageCount is below 4, or an unknown field is sent). The error body contains the field-by-field failure from Zod's .flatten() output. Cross-check against Tool reference.

Debugging tips

Slide viewer does not appear or load

Refresh the connector's tool definitions and start a new conversation after upgrading the server. The host must support MCP Apps; text-only clients continue to return deck details and links. Ask to view a deck with get_project.

If the viewer opens but cannot load a slide, confirm project:read access and project membership, then use Try again. The first preview may take longer while the export renderer captures the slide. Open in Encelade remains available. The viewer displays static slide images; video playback, interactive layers, and editing are available in Encelade.

For self-hosted deployments, deploy the export worker's selected-page thumbnail support before the web app. The viewer uses the existing authenticated renderer; it does not need nested iframe permissions or external script/CDN access.

  • Confirm connectivity — claude mcp list (Claude Code) or codex mcp list (Codex). Should show encelade ✓ connected.
  • Inspect tool calls — Claude Code prints tool invocations and their arguments inline; expand a tool block to see exactly what was sent.
  • Re-trigger OAuth — remove and re-add the connector, or run /mcp → encelade → authenticate in Claude Code.
  • Test the endpoint directly — curl -i -H "Authorization: Bearer $TOKEN" https://www.encelade.ai/api/mcp should return a JSON-RPC error pointing at the missing initialization, not a 401.

The Encelade status page reports MCP endpoint health.

Limits & quotas

LimitValue
brief length1–200,000 characters
pageCountauto or 4 or more, up to your plan's page cap
audience, tone, cta≤ 300 characters each
list_projects limit1–100 (default 20)
generate_project rate10 calls per minute
Credits and deck capsSet by your plan (returns 402 with a code)

Privacy & security

  • All requests are scoped to the workspace the API token belongs to. The MCP server cannot read across tenants.
  • Tokens are scope-gated: a token without project:delete literally cannot call delete_project, regardless of the prompt.

For data handling, retention, and subprocessors, see the privacy policy.

Support

When reporting MCP issues, include: the client (Claude Desktop / Code / Codex), the tool name, the run ID if applicable, and the verbatim error message.