---
name: starpop-mcp-setup
description: Connect the Starpop MCP to an AI agent or chat app, so it can create on-brand image, video, speech, and music ads.
title: Set up the Starpop MCP
url: https://starpop.ai/docs/integrations/mcp.md
---

# Set up the Starpop MCP

Starpop generates images, videos, speech, and music, and holds the user's brands, products, and media. It is a remote MCP server:

- Server name: `starpop`
- Server URL: `https://starpop.ai/api/mcp`
- Transport: Streamable HTTP
- Sign-in: OAuth in the browser. Clients register automatically, so there is no API key, client ID, or secret to ask for.
- Cost: connecting is free. Generating media needs a paid Starpop plan and uses its credits. New accounts start on the free plan, which can't generate.

If Starpop's tools are already available in this session, skip to [Verify](#3-verify). If the user asked for something to be made, keep that request: once Starpop is connected, continue it in this chat.

## If you can run commands

Set Starpop up yourself. The user only signs in or creates an account, chooses a plan if asked, and allows access in the browser. Write the user's global configuration and keep their other MCP entries.

**Claude Code on the web** (`CLAUDE_CODE_REMOTE` is `true`): don't install anything. A cloud session can't complete the browser sign-in, and servers added in it are lost with the container. Starpop reaches cloud sessions as a claude.ai connector, so give the user steps 1–4 of [Claude](#claude), then tell them to start a new Claude Code session, where Starpop's tools load. Report `waiting for sign-in`.

### 1. Connect Starpop

**Claude Code**

```sh
claude plugin install starpop --marketplace starpopai/plugins
```

Then start the sign-in in the background. It opens the browser and waits for the user. It needs a terminal, so run it through `script`:

```sh
# macOS
script -q /dev/null claude mcp login plugin:starpop:starpop < /dev/null
# Linux
script -qec "claude mcp login plugin:starpop:starpop" /dev/null < /dev/null
```

On Windows, ask the user to run `/mcp`, select `plugin:starpop:starpop`, and choose Authenticate.

**Codex CLI**

```sh
codex plugin marketplace add starpopai/plugins && codex plugin add starpop@starpop
```

Then run `codex mcp login starpop` in the background. It opens the browser and waits for the user.

**Hermes**: add this to `~/.hermes/config.yaml`, merging it into any existing `mcp_servers`. Then run `hermes mcp login starpop` in the background and `hermes mcp test starpop` once it finishes.

```yaml
mcp_servers:
  starpop:
    url: "https://starpop.ai/api/mcp"
    auth: oauth
```

**Any other MCP client** (Cursor, VS Code, OpenCode, and so on): add a remote server named `starpop` with the URL `https://starpop.ai/api/mcp` to its global MCP configuration, using Streamable HTTP and no headers. The client starts the sign-in when it next loads.

### 2. While the user signs in

Tell the user in one message what the browser shows: a Starpop page where they sign in or create an account (new accounts get a 6-digit code by email), choose a plan if the page offers one so the first generation works right away, and click **Allow access**. Then wait for the command to finish, which happens once they've allowed access. If the browser can't open on this machine, give the user the sign-in link the command printed.

### 3. Verify

Starpop's tools load in a new session. If they're already loaded, call `list_workspaces`; it returns the user's Starpop organizations and spends no credits. Otherwise tell the user to start a new session (in Claude Code they can also run `/mcp` here), and give them a copyable message that repeats their original request with the details you've gathered, so the new session picks it up.

If the workspace's `billing.error` is set, nothing can generate yet. A new account is on the free plan. Give the user its `billingUrl` now, to open in the browser where they signed in to Starpop, rather than discovering the block on a generation.

### 4. Report

Always end with this block, with only what you checked:

```text
Starpop: <ready|waiting for sign-in|waiting for restart|blocked: reason>
Client: <client>
Workspaces: <names|pending|blocked: reason>
Next step for the user: <what to do>
```

## If you can't run commands

Chat apps can't add a connector for the user. Ask which app they use if it isn't clear. Then send all of that app's steps in one message, with the server URL and button labels filled in. In some apps, such as Claude's desktop app, the connector form covers the chat, so don't ask the user to reply until they have finished every step. When they're back, they say **continue** and you pick up their original request.

If the app needs a new chat after connecting, give the user a copyable message that repeats their original request with the details you've gathered, so they don't have to retype it.

### ChatGPT

Custom plugins are added on chatgpt.com. On a work account, an admin may need to allow them.

1. Open https://chatgpt.com/plugins, click **+**, then **Add custom MCP server**.
2. Upload the icon from https://starpop.ai/docs/integrations/mcp/starpop-icon.png and name it **Starpop**. Set the description to `Use for ads and marketing content: generate on-brand images, videos, voiceovers, and music; search proven ads; analyze videos; and edit finished ads with your saved brands, products, and media.`. Under **Connection**, keep **Server URL** and paste `https://starpop.ai/api/mcp`. Set **Authentication** to **OAuth** and leave the client ID and secret empty.
3. Select **I understand and want to continue**, then click **Create as a plugin**.
4. Find Starpop in the **Personal** plugins and click **Install**.
5. A Starpop page opens. New users click **New to Starpop? Create an account** and enter the 6-digit code emailed to them; existing users sign in. Then they choose the organizations this app can use and click **Allow access**. If the organization is on the free plan, the page first offers **Choose a plan**, so the first generation works right away.
6. In a new chat, type **@**, choose **Starpop**, and send: `Use Starpop to list the workspaces I can access.`

### Claude

The Free plan allows one custom connector. On Team and Enterprise plans, an owner adds Starpop under **Organization settings → Connectors** first, and the user only clicks **Connect**.

1. Open https://claude.ai/customize/connectors, click **+ Add**, then **Add custom connector**.
2. Name it **Starpop**, paste `https://starpop.ai/api/mcp` into **MCP server URL**, and click **Continue**.
3. On the next screen, keep the detected sign-in settings (**Sign in now** and **Register automatically**) and click **Add**.
4. Click **Connect** next to Starpop.
5. A Starpop page opens. New users click **New to Starpop? Create an account** and enter the 6-digit code emailed to them; existing users sign in. Then they choose the organizations this app can use and click **Allow access**. If the organization is on the free plan, the page first offers **Choose a plan**, so the first generation works right away. When the browser then offers to open Claude, they click **Open desktop app** and confirm **Open Claude**, or go back to Claude on the web.
6. Claude may open on its connector settings. Go back to the same chat and say **continue**. If Starpop's tools don't appear, click **+**, choose **Connectors**, switch on **Starpop**, and say **continue** again.

### Gemini

Custom apps need a personal Google Account with Gemini Apps Activity on. Work and school accounts aren't supported yet.

1. On https://gemini.google.com/app, click **Customize** in the sidebar, open the **Connectors** tab, and click **+ Custom**.
2. Paste `https://starpop.ai/api/mcp` as the MCP server URL and click **Next**. Leave **Advanced features** closed.
3. Follow the prompts until the Starpop page opens. The user signs in, chooses the organizations Gemini can use, and clicks **Allow access**.
4. In a new chat, type **@**, choose **Starpop**, and send: `Use Starpop to list the workspaces I can access.`

### Grok

Custom connectors may need a paid Grok plan.

1. Open https://grok.com/connectors, click **New Connector**, then choose **Custom**.
2. Name it **Starpop**, paste `https://starpop.ai/api/mcp` as the server URL, and click **Add Connector**.
3. A Starpop page opens. New users click **New to Starpop? Create an account** and enter the 6-digit code emailed to them; existing users sign in. Then they choose the organizations this app can use and click **Allow access**. If the organization is on the free plan, the page first offers **Choose a plan**, so the first generation works right away.
4. In a new chat, send: `Use Starpop to list the workspaces I can access.`

The app should list the user's Starpop workspaces. This spends no credits.

## After connecting

- Continue the user's original request in this chat. If the workspace's billing reports an error, give the user its billing link before planning a generation, and continue when they say it's done.
- Skills come with the connection, so there is nothing else to install. Call `list_skills` to see them and `get_skill` to read one. Load `starpop-foundations` before planning or generating.
- Agents with file access also save finished outputs to `starpop/<project>/`. Local editing and export checks need `ffmpeg` and `ffprobe`. Without them, Starpop's editor assembles the video.
- To disconnect, remove Starpop from the client, or revoke it in Starpop under **Settings → Connected agents**.

## Troubleshooting

- **Authentication or permission error:** repeat the sign-in step and approve the requested permissions.
- **Workspace or project unavailable:** check the user signed in with the right account and allowed that organization under **Settings → Connected agents**.
- **Tools don't appear after signing in:** restart the client or start a new session. In chat apps, mention Starpop in the message and check it is switched on for the chat.

Full guide with screenshots, permissions, and client support: https://starpop.ai/docs/integrations/mcp
