Tools reference

The Popcorn Editor MCP server exposes 8 tools, 2 resources, and 1 prompt. Everything is scoped to your active workspace and permission-checked server-side — 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. Read the two resources (schema + authoring guide).
2. Author a Design Document.
3. Loop validate-design until it returns ok.
4. create-design, then open or report the editor_url.

Tools#

validate-design#

Checks a Design Document without creating anything. Returns ok or a list of errors. It's free and side-effect free — agents should loop on it to self-repair a document before creating.

create-design#

Validates and compiles a DDS into a new design in your active workspace. Returns uuid, title, and editor_url.

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. If the design uses master pages or reusable blocks, the response includes a warning — decompiling flattens them.

update-design#

Replaces a design's content with a new DDS. 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.

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.

create-design-from-template#

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

Resources#

Agents should read both before authoring:

• 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 resources, 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.
• MCP usage consumes no AI credits — the connected agent brings its own model; Popcorn only validates and compiles documents server-side.

See Tokens & security for authentication details, and the connection guides for Claude, ChatGPT, Gemini, and other clients.