Tools reference

The Popcorn Editor MCP server exposes 12 tools, 2 resources, and 1 prompt. Everything is scoped to your active workspace and permission-checked server-side, so agents can never read other users' data, touch admin functions, or write raw editor state. Designs are exchanged in the Design Document (DDS) format; if you'd rather generate designs over plain HTTP with the built-in AI, see the API.

The recommended agent workflow:

1. get-schema to learn the format, including the prose guide and worked examples.
2. Author a Design Document.
3. Loop validate-design until it returns ok, then analyze-design for layout problems.
4. create-design, then render-design to look at the result and fix what is visibly wrong.

Credentials without write access do not see the writing tools at all. A read-only agent token is offered only the reading tools listed below.

Reading and checking#

get-schema#

Returns the Design Document JSON Schema, which is the exact format the writing tools accept. Two other sections are available: section: "guide" returns the prose authoring guide (structure, units, color, typography, layout rules), and section: "examples" returns a small gallery of complete, valid documents covering the things that are easy to guess wrong, such as curved text, stroke-only shapes, dielines and threaded columns. Agents should call this before authoring anything.

validate-design#

Checks a Design Document without creating anything. Returns ok or a list of findings, each with the path and element it refers to. Errors are blocking; warnings are advisory. It is free and side-effect free, so agents should loop on it to self-repair a document before creating.

analyze-design#

A layout and legibility report that needs no rendering: elements sitting off the artboard, fixed text frames whose copy overflows, curved text that will not fit its path, elements substantially covering other elements, and low-contrast text. Text measurements are estimates and are flagged as such; geometry findings are exact. Takes an inline document or the uuid of a saved design.

render-design#

Renders a design's artboards to preview images so an agent can see the actual result and iterate on what it finds. Options: artboards (0-based indexes, default all), max_edge (128 to 1600 pixels, default 700) and format (jpeg or png).

list-designs#

Lists designs in the active workspace. Supports search and pagination (20 per page). Designs with an open collaboration session are flagged is_live.

get-design#

Reads a design decompiled back to DDS (never raw editor state) plus metadata including editor_url. A single artboard can be fetched instead of the whole document. If the design uses page templates or reusable blocks, the response includes a warning, because decompiling flattens them.

list-templates#

Browses the template gallery (metadata only). Supports search, category, subcategory, and free_only filters. Premium templates are listed with locked: true for users on the free plan.

get-template#

Returns a template's metadata plus its content as DDS when accessible. Premium templates return locked: true without content for free users.

Writing#

create-design#

Validates and compiles a DDS into a new design in your active workspace. Returns uuid, title, and editor_url, plus a preview image of the first artboard when rendering is available. Accepts an optional idempotency_key so a retried call returns the same design instead of creating a duplicate.

patch-design#

Applies small, key-addressed edits without resending the whole document. Operations are set-meta, set-artboard, add-artboard, duplicate-artboard, remove-artboard, set-element, add-element and remove-element, up to 50 per call. The patched document is fully validated before anything is written, the change is all-or-nothing, element identity is preserved, and the previous state is snapshotted first. remove-artboard is refused for the last remaining artboard.

This is also how agents build long documents safely: create the first page, then add one page per patch, so a failure never loses the pages already placed.

update-design#

Replaces a design's content with a new DDS, for wholesale rewrites. Element identity is preserved for keys you keep. Before writing, the previous state is snapshotted as a restorable version ("Before agent update", visible in version history).

Designs with a live collaboration session are refused unless the agent passes fork_if_live: true, which writes to a new copy instead. The response then has forked: true. patch-design behaves the same way.

create-design-from-template#

Starts a design from a template (premium templates require a paid plan). Returns uuid and editor_url.

Resources#

The same content get-schema returns is also published as MCP resources, for clients that prefer to read resources up front:

• design-document-schema - the JSON Schema of the DDS format. popcorn://schemas/design-document.v1.json
• design-authoring-guide - a markdown guide to authoring good documents. popcorn://guides/design-authoring.md

Prompts#

• author-design-document (argument: brief) - a guided end-to-end workflow: it walks the agent through reading the format, authoring, validating, and creating a design from your brief.

Scoping and limits#

• All calls run against your personal workspace by default. Send an optional X-Workspace header with a workspace uuid to target a team workspace.
• Rate limit: 60 requests/minute per user.
• A document sent inline is capped at 2 MB, and a design at 50 artboards and 2000 elements.
• patch-design accepts at most 50 operations per call; render-design returns at most 6 artboards per call.
• Your workspace's design limit still applies, exactly as it does in the app.
• MCP usage consumes no AI credits. The connected agent brings its own model; Popcorn only validates and compiles documents server-side.
• There is no export tool. Agents author print-correct documents; you export the PDF from the editor. See print-ready PDF.

See Tokens & security for authentication details, Is it safe? for what agents can and cannot touch, and the connection guides for Claude, ChatGPT, Gemini, and other clients.