Connect Gemini CLI

Gemini CLI connects to Popcorn's MCP server over streamable HTTP using an agent token sent as a bearer header — no OAuth flow needed. Once connected, Gemini can validate, create, and edit designs in your active workspace using its own model (no Popcorn AI credits are consumed).

Your exact MCP URL is shown in the app under Settings → Your agent access. The examples below use https://app.example.com/mcp/popcorn as a placeholder — swap in yours.

1. Mint an agent token#

In Popcorn, open Settings → Your agent access and create a token. Choose Read & write if you want Gemini to create and update designs (or Read only for browsing), and optionally set an expiry (30/90/365 days). The token is shown once — copy it immediately. You can revoke it anytime from the same section. Details in Tokens & security.

2. Add the server#

One command:

gemini mcp add --transport http popcorn https://app.example.com/mcp/popcorn --header "Authorization: Bearer <token>"

Or edit ~/.gemini/settings.json directly:

{
  "mcpServers": {
    "popcorn": {
      "httpUrl": "https://app.example.com/mcp/popcorn",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

3. Verify#

Start gemini and run:

/mcp

You should see the popcorn server listed with its tools — validate-design, create-design, list-designs, get-design, update-design, list-templates, get-template, and create-design-from-template. See the tools reference for what each does.

4. Try it#

Ask Gemini to make something:

Read the popcorn design-document schema and authoring guide, then create an A5 flyer
for a weekend farmers market — bold type, warm colors. Validate before creating,
and give me the editor link.

A good run reads the two bundled resources, authors a Design Document, loops validate-design until it passes, then calls create-design and returns an editor_url you can open in the browser.

Notes#

• Requests are rate-limited to 60 per minute per user.
• Everything is scoped to your active workspace and permission-checked server-side. To target a team workspace instead of your personal one, add an X-Workspace header with the workspace uuid alongside the Authorization header.
• Live-session protection and the automatic pre-update version snapshots are covered in the tools reference.

Connecting a different client? See Claude, ChatGPT, or other clients, and the overview for how it all fits together.