Authoring decks over MCP

There is no separate deck-building API for agents, the MCP tools listed here are the whole surface. Together they work like a UI: list_layouts and get_layout are the component picker, get_slide and update_slide are the editor, screenshot_page is the preview pane. This page walks through that surface as a workflow, in the order you'd normally reach for it. For the design rules the guides describe (type scale, tokens, spacing, layout catalog), see Designing decks; for the exact input schema of every tool, see the MCP tool reference.

1. Create the presentation

create_presentation seeds a new deck from a theme's starter layouts, a cover, a content slide, and a closing slide, and returns the deck id, its shareable /s/ URL, the layout ids it was seeded with, and a next hint pointing at the next step. Omit theme and it uses the workspace's own brand theme when it has one (asking which, if there are several), otherwise the built-in sharemypage theme.

2. Get briefed before writing any slide HTML

Before hand-authoring or editing a slide's markup, call one of:

• get_design_guide, guided mode: the theme's type scale, color tokens, spacing rhythm, layout catalog, and the do/don't checklist the in-app AI editor itself is briefed with. Accepts a builtin or custom theme id.
• get_developer_guide, freeform mode: how to hand-author a slide's full HTML and its own scoped CSS so it matches a customer's brand, custom fonts, colors, textures, bespoke sections, while still rendering inside the presentation engine. Reach for this instead of, or alongside, get_design_guide when the deck needs to look like the customer's own brand rather than the theme's.

Alongside the guide, list_layouts returns every layout's id, name, and a one-line description for the resolved theme, and get_layout returns one blueprint's complete HTML, ready to pass straight to add_slide or adapt.

3. Build slides

• add_slide adds a slide to the deck. Provide either html (a complete <section class="slide">…</section> fragment) or layout (a blueprint id from list_layouts), and optionally afterSlide (a slideId or 1-based index) to place it, or omit it to append at the end. It runs a non-blocking lint over the new slide's HTML and reports any warnings, for example a class the theme doesn't define, which would render unstyled.
• update_slide replaces a slide's HTML outright. patch_slide makes a targeted find/replace edit to one slide without resending the whole fragment, find must match the slide's current HTML exactly (by default once; pass expectedMatches to change several identical spans at once). For a slide with embedded images, prefer patch_slide over update_slide so you aren't resending the whole asset blob just to change some text.
• move_slide, duplicate_slide, and delete_slide reorder, copy, or remove a slide by slideId or 1-based index (delete_slide refuses to remove a deck's last slide).

4. Read slides safely, and edit concurrently without clobbering

get_slide returns one slide's HTML, title, and currentVersionId. Pass that value back to update_slide as expectedVersionId: if the slide changed since you read it (another edit landed in between), the write is refused and you're told to re-fetch, reconcile, and try again, rather than silently overwriting someone else's change. Omit expectedVersionId for last-write-wins.

get_slide also elides large embedded base64 assets (a pasted logo or screenshot) into a short placeholder token by default, with a manifest of what was stripped, so reading an asset-heavy slide doesn't cost tokens just to see its text. Pass assets: "inline" to get the raw HTML back if you actually need it.

5. Check your work visually

screenshot_page renders a page's or presentation's current content in a real headless browser and returns an image, so you can visually check layout, overflow, and broken images instead of only inspecting the HTML. For a presentation it shows the first slide by default; pass slide (a slideId or 1-based index from list_slides) to render a different slide instead, full-bleed, exactly as the live viewer would show it active.

6. Add images

add_image uploads an image and returns a URL to reference in a slide. Decks keep images by URL, never inline base64. Provide either url (a public http(s) image fetched server-side) or dataBase64 plus contentType, up to 4 MB, PNG, JPEG, GIF, WebP, or SVG. Drop the returned URL into an <img src="…"> via add_slide, update_slide, or patch_slide.

7. Brand it with a theme

• list_themes lists every theme available to the workspace, builtin and custom, with each one's kind and whether it canBeBase for a new custom theme.
• create_theme creates a workspace-scoped custom theme: a builtin base theme (its layouts, CSS, and engine) with your own brand tokens substituted in. A primary accent token is required; canvas tokens (canvas, ink, inkMuted, panel, line) re-skin the whole component system at once for a more brand-specific look (dark, forest, warm-paper, and so on); brandCss appends plain CSS for texture or label styling; fontUrl loads an extra brand font; logoLightUrl / logoDarkUrl set the theme's own logo lockup. Pass the returned theme id as create_presentation's theme argument.

An alternative entry point: importing a PowerPoint

Instead of building a deck slide by slide, an existing .pptx file can be imported as a native deck, in two tool calls:

1. request_presentation_upload_url returns a short-lived URL to PUT the raw .pptx bytes to directly (so any file size works) plus a token.
2. import_uploaded_presentation takes that token and builds the deck.

The importer reads the file's text, tables, and images straight from the file, nothing is invented, matches them to the target theme's layouts, and hosts images automatically. Two modes control how: reauthor (the default) has the model lay out the real content into the theme's layouts, grounded in the file so it can't fabricate facts; faithful is a plain, deterministic 1:1 reproduction with no model involved. A slide the importer can't reproduce faithfully, a dense logo wall, a custom diagram, a very dense table, is deferred: kept as a placeholder with a suggested fix rather than faked. Omit theme here too and it resolves the same way as create_presentation, the workspace's own brand theme first.

See also

• Designing decks for the type scale, tokens, spacing, layout catalog, and do/don't rules these tools are meant to produce.
• Slide decks for a plainer walkthrough of what a deck is.
• MCP tool reference for the complete deck, slide, and theme tool list.