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:
- Open Settings → API tokens and confirm the token is still active.
- Confirm the token has every scope listed for the tool in Tool reference — a
project:read-only token cannot callupdate_project. - 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) orcodex mcp list(Codex). Should showencelade ✓ 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/mcpshould return a JSON-RPC error pointing at the missing initialization, not a 401.
The Encelade status page reports MCP endpoint health.
Limits & quotas
| Limit | Value |
|---|---|
brief length | 1–200,000 characters |
pageCount | auto or 4 or more, up to your plan's page cap |
audience, tone, cta | ≤ 300 characters each |
list_projects limit | 1–100 (default 20) |
generate_project rate | 10 calls per minute |
| Credits and deck caps | Set 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:deleteliterally cannot calldelete_project, regardless of the prompt.
For data handling, retention, and subprocessors, see the privacy policy.
Support
- Email: support@encelade.ai — typical response within 24 hours.
- Status: encelade.ai/status — current MCP endpoint health and recent incidents.
- Support center: encelade.ai/support — contact form and broader help articles.
When reporting MCP issues, include: the client (Claude Desktop / Code / Codex), the tool name, the run ID if applicable, and the verbatim error message.