AI agents (MCP)
Tools reference
The Popcorn Editor MCP server exposes tools according to your account permissions and the features enabled on the server. A read-only connection will not see write tools. Asset tools may also be absent when asset integration is disabled. Use the tool schema your client receives as the source for current arguments.
Designs move through MCP as Design Documents. The server does not expose raw editor state. For a new design, read the schema, validate the document, create it, then render and inspect the result.
Read and plan
| Tool | Use |
|---|---|
| get-schema | Get the Design Document schema, authoring guide, or examples. |
| validate-design | Find blocking errors and advisory warnings before writing. |
| analyze-design | Check layout and legibility without rendering. |
| render-design | Preview selected artboards as images. |
| list-workspaces | Find workspaces you can access and their UUIDs. |
| list-designs | Find saved designs in a workspace. |
| get-design | Read a saved design as a Design Document, optionally one artboard. |
| list-templates | Search the template catalog. |
| get-template | Read a template and its design content when permitted. |
| get-operation | Check whether a timed-out mutation committed. |
A workspace UUID can be passed to creation, listing, and asset tools when you need a team workspace. Use list-workspaces first instead of guessing an identifier. get-design returns a revision for edits to an existing design.
Write and recover
| Tool | Use |
|---|---|
| create-design | Save a validated Design Document as a new design. |
| create-design-from-template | Start a design from an accessible template. |
| patch-design | Add, remove, or change keyed elements, artboards, styles, and metadata. |
| update-design | Replace the whole design content with a revised document. |
| restore-design-version | Restore a version created by an agent edit when the user explicitly wants that rollback. |
Use patch-design for small changes. It validates the complete result and saves the previous state as a version. Use update-design for a wholesale rewrite. For live collaboration, supply the revision from get-design and a stable request ID so overlapping edits can be detected. If a write times out, call get-operation with that request ID. A “not found” response does not prove the original write failed; retry only with the same request ID and arguments.
Images and assets
| Tool | Use |
|---|---|
| prepare-asset-upload | Obtain a scoped HTTP upload for a local image using its name, byte count, and SHA-256. |
| import-asset | Store a public HTTP(S) image in the workspace. |
| list-assets | Browse stored assets with bounded pagination. |
| get-asset | Inspect an asset without returning image bytes. |
| repair-design-assets | Convert retrievable legacy image sources in a saved design to durable assets. |
Use the returned asset ID in image elements. Transfer local file bytes through the upload URL, not through MCP as base64. Using images with an AI agent gives the step-by-step flow and explains which old sources cannot be repaired automatically.
Resources and limits
The server also publishes a Design Document schema resource, an authoring guide resource, and an authoring prompt for clients that support MCP resources and prompts. Workspace permissions, plan limits, and server-side validation apply to tool calls just as they do in the editor. Validation itself does not create a design or spend AI credits. A connected agent uses its own model; Popcorn validates, stores, and renders the design.