Tokens & security

External agents reach Popcorn through the MCP endpoint at your app origin + /mcp/popcorn (your exact URL is shown under Settings → Your agent access). Every request is authenticated and permission-checked server-side, so an agent can never do more than the account that authorized it. This page covers both credential types, what agents can and can't do, and how to shut access off.

If you are weighing up whether to connect at all, start with Is it safe to connect an AI agent?, which answers the same questions without the mechanics.

MCP is a paid-plan feature: connecting agents and minting tokens require a Popcorn plan that includes agent access (any member of a paying workspace qualifies). Without one, requests are refused with a 403 telling you to upgrade, and existing tokens stay visible and revocable in Settings but stop working.

Agent tokens#

Agent tokens are bearer credentials for CLIs and IDEs (Claude Code, Gemini CLI, Cursor, VS Code). To mint one:

1. Open Settings → Your agent access.
2. Choose the scope: Read & write (create and edit designs) or Read only.
3. Optionally set an expiry: 30, 90, or 365 days. Tokens do not expire unless you choose one.
4. Copy the token. It is shown once. If you lose it, revoke it and mint a new one.

Clients send the token as a standard Authorization: Bearer header:

curl https://popcorneditor.com/mcp/popcorn \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A valid token returns the tool list; a missing or revoked one gets a 401.

Each token in Your agent access shows when it was last used, which makes it easy to spot one you set up and forgot. Revoke any of them from the same section and requests using it fail immediately.

Treat an agent token like a password for your account. It is not recoverable, and anyone holding it can act as you. Prefer Read only for agents that only need to inspect or report on designs, set an expiry unless you have a reason not to, mint a separate token per tool so you can revoke one without breaking the others, and never paste one into a shared document or repository.

OAuth connections#

Connector UIs (Claude on web, desktop and mobile, and ChatGPT on the web) use OAuth 2.1 instead of a pasted token. You add the MCP URL, leave any OAuth Client ID/Secret fields blank (the server registers the client automatically), sign in to Popcorn, and approve an Authorize consent screen.

What the consent grants:

• The connected AI app can read and write as you: list, read, create, and edit designs in your workspaces, with exactly your permissions.
• Access tokens expire after 24 hours and refresh automatically for up to 30 days without re-consent.

To revoke, remove the connector in the AI app. Access lapses at the next token refresh. Setup steps per client are in Connect Claude and Connect ChatGPT, and Where you can connect explains which method each app needs.

What agents can and can't do#

Nothing is enforced on the client side. The server checks every call:

• Workspace-scoped. Every tool operates on your active workspace by default (your personal workspace). An optional X-Workspace header with a workspace uuid targets a team workspace instead, and only one you're an active member of. Anything else is refused.
• Your permissions, no more. Agents can never read other users' data, touch admin functions, or write raw editor state. They only exchange validated Design Documents.
• Read-only means read-only. A read-only token can list and read designs and templates (and validate, analyze and render, which have no side effects) but cannot create or edit anything. The writing tools are not even offered to a read-only credential.
• Nothing can be deleted. There is no delete tool. The strongest actions are replacing a design's content or removing an element or artboard, and the last remaining artboard cannot be removed.
• Destructive edits are recoverable. Before update-design or patch-design writes, the previous state is snapshotted as a restorable version ("Before agent update" in version history), tagged so agent edits are distinguishable from your own.
• Live sessions are protected. A design with an open collaboration session refuses writes unless the agent explicitly passes fork_if_live: true, which writes to a new copy instead.
• Premium stays gated. Premium template content is withheld from free-plan users (locked: true) exactly as it is in the app.
• No billing or account access. There are no billing, plan or account tools.
• No AI credits are spent. The connected agent brings its own model; Popcorn only validates and compiles documents server-side.

The full tool list is in the tools reference.

Limits#

• 60 requests per minute per user. Well-behaved agents (the validate then create loop described in the overview) stay well under this; if an agent hits the limit, it should back off and retry.
• 2 MB per document sent inline, 50 artboards and 2000 elements per design.
• 50 operations per patch-design call, and 6 artboards per render-design call.
• Your workspace's design limit applies to agent-created designs too.

For administrators#

Admins can disable external agent access account-wide from the admin settings. While disabled, all agent access stops at once, and every token and OAuth connection is refused, with no per-user cleanup required.