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 — 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.

Agent tokens#

Agent tokens are long-lived 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.
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://app.example.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.

Revoke a token anytime in the same Your agent access section — requests using it fail immediately. Prefer Read only tokens for agents that only need to inspect or report on designs, and set an expiry unless you have a reason not to.

OAuth connections#

Connector UIs (Claude.ai web, Claude Desktop, ChatGPT) use OAuth 2.1 instead of a pasted token. You add the MCP URL, leave any OAuth Client ID/Secret fields blank (the server supports dynamic client registration), 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.

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 — one you're a member of.
• 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 documents, which has no side effects) but cannot create or edit anything.
• Destructive edits are recoverable. Before update-design replaces content, the previous state is snapshotted as a restorable version ("Before agent update" in version history).
• Live sessions are protected. A design with an open collaboration session refuses update-design 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 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#

MCP requests are rate-limited to 60 requests per minute per user. Well-behaved agents (the validate → create loop described in the overview) stay well under this; if an agent hits the limit, it should back off and retry.

For administrators#

Admins can disable the entire MCP server instantly under Admin → Settings → External agent access (MCP). While disabled, all agent access stops at once — every token and OAuth connection is refused — with no per-user cleanup required.