Docs

Tool reference

MCP tools — parameters, scopes, behaviors, and example prompts.

Each MCP tool enforces the scopes listed below (see Setup).

All write tools accept structured input only — they never parse natural language directly. The client (Claude, Codex, etc.) is responsible for translating the user's prompt into the parameters documented here.

list_projects

List presentation projects in your workspace. Paginated; pass the returned cursor to fetch the next page.

  • Scope: project:read
  • Behavior: read-only, idempotent

Parameters

NameTypeRequiredConstraintsDefault
cursorstringnoopaque, returned by a prior call—
limitnumberno1–10020

Returns — { projects, nextCursor, hasMore }. Each project summary includes id, pid, name, theme, page-layout settings, publish state, members (with roles), createdAt / updatedAt, pinnedAt, and firstPageId. nextCursor is opaque (pass it as cursor on the next call) or null when there are no more pages.

Example prompt

"List my Encelade projects and show me the most recent five."


get_project

Get a single project by its public ID (pid).

  • Scope: project:read
  • Behavior: read-only, idempotent

Parameters

NameTypeRequiredConstraints
pidstringyesnon-empty

Returns — Full project record: pid, name, theme, branding, page-layout/grid settings, publish state, the pages array, members (each with a role — the owner is the member with role: "owner"), createdAt / updatedAt, and your pinnedAt for the project (or null).

In ChatGPT and Claude hosts that support MCP Apps, this tool also opens a slide viewer. Select a slide or use the previous/next buttons to navigate. Open in Encelade opens the selected slide for editing. The viewer is read-only and loads slide images on demand; visited slides gain thumbnails. The text response also includes a link to the deck for clients without MCP Apps support.

The viewer requires project:read and project membership (or a tenant admin role). Decks do not need to be published. Image data is delivered only to the UI, without render tokens or public image URLs.

Example prompt

"Show me the details of the deck with pid abc123, including its pages and collaborators."


get_slide_preview

This read-only tool is visible to the MCP Apps viewer. It accepts a non-empty pid and a UUID pageId, requires project:read, and checks access to that page before reading or rendering its private preview. It returns { pid, pageId, status } as text and the image in UI-only result metadata. The status is ready, or loading when another render is in progress. Rendering failures return a tool error so the viewer can offer a retry.


update_project

Update an existing project's name or theme.

  • Scope: project:write
  • Behavior: write, idempotent

Parameters

NameTypeRequiredConstraints
pidstringyesnon-empty
namestringno1–255 characters
themestringnovalid theme slug

You must pass at least one of name or theme. Tenant admins and project owners/editors/content editors can update; viewers cannot.

Returns — The updated project record.

Example prompt

"Rename my 'Q3 Report' deck to 'Q3 2026 Quarterly Review' and switch its theme to obsidian."


edit_project

Edit an existing deck from a plain-language instruction, the way the editor's AI chat does: rewrite or translate text, restyle layers, add, reorder or delete pages, change the theme.

  • Scope: project:ai-chat
  • Behavior: write, destructive (can delete pages), non-idempotent
  • Rate limit: 10 calls per minute, shared with POST /api/public/v1/projects/{pid}/edits

Parameters

NameTypeRequiredConstraints / default
pidstringyesnon-empty
instructionstringyes1–4,000 chars: what to change
pageIdstringnoa page id from get_project; the page an instruction that names no pages applies to
dryRunbooleannofalse (default); true reports the changes without saving them

Tenant admins and project owners/editors can edit; content editors and viewers cannot. Every call uses AI credits, dry runs included.

Returns — { status, message, changes, skipped, changedPageIds, deletedPageIds }. message is the assistant's reply; changes lists each change as { tool, details } and skipped each change it could not make as { tool, reason }. status is one of:

StatusMeaning
appliedThe changes were saved.
proposeddryRun was true; nothing was saved.
no_changesThe instruction led to no change.
truncatedThe edit hit its output or step limit and nothing was saved. Split the request.

Page content is not returned: call get_project to read the edited deck.

Errors you can act on — returned as a tool error:

  • Out of AI credits — the error text is JSON, { code: "CREDITS_EXHAUSTED", message, limit, upgrade_url }, so branch on code. A credit pack or a bigger plan clears it.
  • Page not found — pageId is not a page of this deck.
  • The deck changed while the edit ran — someone saved the deck mid-edit, so nothing was saved. Retry.

Example prompt

"In my 'Q3 Review' deck, translate every page into German and delete the appendix."


delete_project

Permanently delete a project. This cannot be undone.

  • Scope: project:delete. An OAuth connection has it only if the client requested it at sign-in; otherwise delete decks in the Encelade app.
  • Behavior: destructive, non-idempotent

MCP clients annotate this tool as destructive — Claude Desktop and Claude Code will ask for confirmation before invoking it.

Parameters

NameTypeRequiredConstraints
pidstringyesnon-empty

Returns — { deleted: true, pid: "<the pid>" } on success.

Example prompt

"Delete the deck named 'Untitled Draft' from my workspace."


generate_project

Generate a deck, one-pager or proposal from a brief. Returns a runId immediately; the run plans and builds the pages in the background.

  • Scope: project:generate
  • Behavior: write, non-idempotent; with research: true the run searches the web
  • Rate limit: 10 calls per minute, and a cap on runs in progress at once

Parameters

NameTypeRequiredConstraints / default
briefstringyes1–200,000 chars: the request plus any notes, data or research to build from
artifactTypeenumnodeck (default), one_pager, proposal
pageCount"auto" or integernoauto (default) or 4 or more; a one-pager is always one page
localestringnoen, de, es or uk; detected from the brief when omitted
researchbooleannofalse (default); true lets the run search the web
audiencestringno≤ 300 chars
tonestringno≤ 300 chars
ctastringno≤ 300 chars, the call to action
styleenumnoclassic (default) or cinematic; decks only
onePagerDesignenumnoauto (default), editorial, bands, modular; one-pagers only
themestringnoauto (default), a built-in theme id, or tenant-theme:<uuid> from list_themes
fitToPageCapbooleannofalse (default); true condenses into your plan's page cap instead of failing

There are no file uploads or connectors: paste the source text into brief. Links in the brief are read.

Returns — { runId, projectPid, status: "queued" }. Poll with get_generation_run.

Plan limits. When the workspace is out of credits, out of storage or the request is over the plan's limits, the tool error's text is JSON: { code, message, required_plan, limit, upgrade_url }. code is CREDITS_EXHAUSTED, PAGE_LIMIT_EXCEEDED, PRO_REQUIRED, PRESENTATIONS_EXHAUSTED, PROPOSAL_CREATION_REQUIRED or STORAGE_FULL. required_plan is left out when no single plan clears the limit (a credit pack clears CREDITS_EXHAUSTED, deleting files clears STORAGE_FULL), and limit ({ key, value, used }) when the error is not about a count. Branch on code rather than string-matching. Other errors are plain text.

Example prompt

"Create a 10-page presentation about the impact of AI on healthcare. Use a professional tone aimed at hospital executives."


get_generation_run

Check the progress of a run started by generate_project. Poll every 5–15 seconds; a run takes a few minutes.

  • Scope: session:read or project:generate
  • Behavior: read-only, idempotent

Parameters

NameTypeRequiredConstraints
runIdstringyesUUID

Returns — A one-line status plus the run:

FieldNotes
phaseplanning, generating, done or failed. Stop polling at done or failed.
statusThe run's stage: queued, intake, researching, planning, writing, composing, done, failed or canceled.
linkThe project URL, available from the start.
projectPidThe project's public ID, for get_project.
error{ stage, code } when the run failed, otherwise null.
startedAt, finishedAtISO 8601 timestamps, or null.
plan{ title, pageCount, pages } once planned, otherwise null.

Example prompt

"Check on the deck you are generating and give me the link when it's done."


cancel_generation_run

Stop a run started by generate_project. Pages it already wrote stay in the deck; the run ends canceled (phase failed in get_generation_run).

  • Scope: session:write or project:generate
  • Behavior: idempotent; a run that already finished returns an error

Parameters

NameTypeRequiredConstraints
runIdstringyesUUID

Returns — { status }, the run's status after the cancel was recorded.

Example prompt

"Stop generating that deck."


list_themes

List the custom themes in your workspace, newest first. Pass a theme's themeId as theme to generate_project to build decks in it.

  • Scope: theme:read
  • Behavior: read-only, idempotent

Parameters — none.

Returns — { themes }. Each theme has themeId (tenant-theme:<uuid>), name, mode ("light" or "dark"), accent, background, highlightStyle, updatedAt, and studioUrl (where to edit it in Encelade).

Example prompt

"Which Encelade themes do we have? Make a deck about Q3 results in our Acme theme."


create_theme

Create a custom theme from brand colours, fonts and styles — for example when you ask your AI tool to "send our theme to Encelade". Requires the Editor or Admin workspace role.

  • Scope: theme:write
  • Behavior: write, not idempotent (each call creates a new theme); reaches Brandfetch when a logo is requested
  • Rate limit: 5 per minute and 20 per hour, per person

name and colors.accent are required. Anything left out is derived from the colours you give (for example readable text for a dark background) or kept from Encelade's default theme. All colours are hex (#e63946 or #e39).

Parameters

NameTypeRequiredNotes
namestringyesIf the workspace already has a theme with this name, a number is added: Acme (2).
colorsobjectyesaccent (required), accentMuted, background, panel, card, border, text, mutedText.
chartColorsstring[]no1–8 colours; repeated to fill the theme's 8 chart series.
fontsobjectnobody / heading, each { family, weight? }. Only fonts Encelade offers are applied; others are reported back.
pageBackgroundobjectno{ type: "solid", color } or { type: "gradient", colors (2–5), style?: "linear" | "radial", angle? }.
cardsobjectnofill (same shape as pageBackground), borderColor, borderWidth (0–20), cornerRadius (0–50), shadow.
titleCardobjectnoSame as cards, without shadow. Gives decks a title card.
contrastobjectnoOpposite-mode palette for emphasis slides: background, panel, card, border, accent, text, mutedText. Send {} to derive it.
highlightStylestringnoHow decks mark key phrases in headlines and tables: accent (default), bold-muted, bold or highlighter.
logoobjectnobrandDomain (the brand's website, e.g. acme.com), position, widthPercent (3–15). Encelade looks up the logo the brand publishes (via Brandfetch).

Unknown fields are rejected, so a misspelled field fails rather than being silently ignored.

Returns — { themeId, name, renamed, studioUrl, logo, derived, notApplied }. logo is { domain, kind } when a logo was added, otherwise null; derived lists the colours Encelade filled in; notApplied lists anything it could not use, with a reason.

A logo is optional, so a failed lookup never fails the call: the theme is created without a logo and notApplied says why (no brand found for the domain, no logo made for the theme's background, lookup unavailable). Encelade only uses the version of the logo made for the theme's background, plus the opposite version for contrast slides, never a version that could disappear against the slide.

Example prompt

"Send Encelade our theme: accent #E63946, dark navy background #1D3557, Inter for headings, and our logo from acme.com."


update_theme

Change an existing custom theme — for example "make our Acme theme's accent orange". Requires the Editor or Admin workspace role.

  • Scope: theme:write
  • Behavior: write, destructive (overwrites the stored values); reaches Brandfetch or downloads files when a logo, font or image link is given
  • Rate limit: 10 per minute and 60 per hour, per person

The change applies at once to every deck that uses the theme, and there is no undo. Only the fields you pass change; everything else is kept.

Parameters — themeId (required, from list_themes), an optional name, and any of the create_theme fields, all optional:

  • chartColors and backgroundVariants replace the whole list; backgroundVariants: [] removes every variant.
  • contrast merges into the stored palette; null removes it. titleCard: null removes the title card. highlightStyle: null returns to accent.
  • logo with brandDomain, url or svg replaces the logo, keeping its placement unless you pass position / widthPercent. A logo with only position / widthPercent moves or resizes the current logo. logo: null removes it.
  • name renames the theme. If another theme already has that name, the call fails and nothing is changed.

Returns — { themeId, name, studioUrl, changed, derived, decksUsingTheme, logo, customFonts, notApplied }. changed lists the fields that now differ; derived lists the ones that changed as a result of others (for example text colours re-picked for a dark background); decksUsingTheme is how many decks in the workspace use the theme. logo is there only when the call passed a new logo: what was applied, or null if it could not be imported and the theme kept its current one.

A logo, font or image that cannot be imported never fails the call: the theme keeps its current one and notApplied says why.

Example prompt

"Make our Acme theme dark: background #0B1220 and accent #FF6B35."


delete_theme

Permanently delete a custom theme from the workspace, for everyone in it. Requires the Editor or Admin workspace role.

  • Scope: theme:write
  • Behavior: write, destructive; there is no undo
  • Rate limit: 5 per minute and 20 per hour, per person

Parameters — themeId (required, from list_themes) and confirmDecksUsingTheme (optional).

If any deck uses the theme, the first call deletes nothing. It returns { deleted: false, confirmationRequired: true, themeId, name, decksUsingTheme } so the assistant can tell you how many decks use the theme and ask before deleting. Once you agree, it calls again with confirmDecksUsingTheme set to that count. If the count changed in between, it asks again with the new one. A theme no deck uses is deleted in one call.

Returns — { deleted: true, themeId, name, decksUsingTheme }.

Generated decks keep the look the theme had when they were created. New decks can no longer use the theme.

Example prompt

"Delete the old Acme 2024 theme."