Troubleshooting

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 call update_project.
Re-run the authorize step from the client. In Claude Code: /mcp → encelade → authenticate. In Claude Desktop: remove and re-add the connector.

`PRO_REQUIRED` (free-tier deck cap)

generate_project is gated by the presentations_created entitlement. Starter-plan workspaces have a monthly cap; once exhausted, the tool returns a structured error:

{
  "code": "PRO_REQUIRED",
  "required_plan": "pro_v1",
  "message": "...",
  "limit": { "key": "presentations_created", "value": N, "used": M },
  "upgrade_url": "https://www.encelade.ai/pricing"
}

Branch on code === "PRO_REQUIRED" rather than string-matching. Upgrade at the upgrade_url.

generate_project is capped at 10 calls per window per token (api-generate key prefix). Burst above that and subsequent calls fail until the window resets. Other tools follow the default public-API rate limit.

If you're hitting the cap legitimately, prefer one plan_project call followed by a single generate_project over multiple speculative generations.

"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

plan_project and generate_project are async. The planning phase typically takes 30–90 seconds; the generating phase takes 60–180 seconds depending on slide count.

Do not flag a session as stuck before 5 minutes from its startedAt timestamp. Poll get_generation_session and watch the phase field — not timestamps — to track progress.

If a session is still in planning or generating after 5 minutes, retry by calling generate_project again. If the new session also stalls, contact support with both session IDs.

`Validation failed: ...`

Returned when your input doesn't satisfy the tool's parameter schema (e.g., outlineHints is empty, pageCount exceeds 200, a model ID isn't in the allowed set). The error body contains the field-by-field failure from Zod's .flatten() output. Cross-check against Tool reference.

Debugging tips

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.
Check /status — the Encelade status page reports MCP endpoint health.

Limits & quotas

Limit	Value
`outlineHints` items	1–200
`outlineHints` item length	1–20,000 characters
`pageCount`	1–200
`topic` length	≤ 512 characters
`audience` length	1–256 characters
`tone` length	1–128 characters
`list_projects` `limit`	1–100 (default 20)
`generate_project` rate	10 calls per window per token
Free-plan deck cap	Enforced via `presentations_created` (returns `PRO_REQUIRED`)

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

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 session ID if applicable, and the verbatim error message.