# Connect an AI agent ## Server URL and ways to connect Add the Gumball MCP server to your AI client, and the agent can search shows, read prices and open ad slots, or read your shows, as you. The server URL is the same for every client: ```text https://api.gumball.fm/mcp ``` A client connects in one of two ways: - **By signing in.** The client sends you to gumball.fm, where you approve it as read-only or read and write. You never handle a key. Claude on the web and desktop and ChatGPT connect only this way. The connection ends after 30 days, and you can disconnect it sooner under **Connected Apps** on [Account Settings](https://gumball.fm/user/settings#connected-apps). - **With an API key.** This works in clients that can send a header: Claude Code, VS Code, Codex, and others. First [create an API key](https://gumball.fm/user/settings#api-keys). Keep the key out of files you share or commit. The steps for each client read it from an environment variable named `GUMBALL_API_KEY`. ## Claude ### Claude Code Run this command, with your key in place of `gum_YOUR_KEY`: ```bash claude mcp add --transport http gumball https://api.gumball.fm/mcp --header "Authorization: Bearer gum_YOUR_KEY" ``` Inside a session, `/mcp` shows the server and its tools. To sign in instead of sending a key, leave out `--header`. Then run `/mcp` in a session, select Gumball, and approve Claude Code on gumball.fm. ### Claude on the web and desktop Claude connects to a custom connector by signing in: 1. Go to **Customize > Connectors**. 2. Select **Add**, then **Add custom connector**. 3. Enter the name `Gumball` and the server URL, then click **Continue**. 4. Click **Add**, then **Connect**, and approve Claude on gumball.fm. On a Team or Enterprise plan, an Owner adds the connector under **Organization settings > Connectors** first. ## ChatGPT ChatGPT connects to a custom MCP server by signing in. It can't send an API key. 1. Go to **Plugins** in ChatGPT on the web. 2. Select the plus button, then **Add custom MCP server**. 3. Enter the name `Gumball` and the server URL. 4. Under **Authentication**, select **OAuth**. 5. Review the warning, continue, and select **Create as a plugin**. 6. Open the plugin, install it, and approve ChatGPT on gumball.fm. ## VS Code VS Code with GitHub Copilot reads MCP servers from `~/.copilot/mcp-config.json`, or from `.mcp.json` at the root of a workspace. Add this entry: ```jsonc { "mcpServers": { "gumball": { "type": "http", "url": "https://api.gumball.fm/mcp", "headers": { "Authorization": "Bearer ${GUMBALL_API_KEY}" } } } } ``` Set `GUMBALL_API_KEY` in the environment VS Code starts from. ## Codex Add this entry to `~/.codex/config.toml`. The Codex CLI, the IDE extension, and the ChatGPT desktop app share the file: ```toml [mcp_servers.gumball] url = "https://api.gumball.fm/mcp" bearer_token_env_var = "GUMBALL_API_KEY" ``` Set `GUMBALL_API_KEY` in the environment Codex starts from. ## Any other client A client can connect if it supports remote MCP servers over Streamable HTTP and can either sign in or send a request header. To sign in, give the client the server URL alone. It finds Gumball's sign-in server from the MCP server's answer, registers itself, and sends you to gumball.fm to approve it. To use a key, give it these values: | Setting | Value | |---|---| | Server URL | `https://api.gumball.fm/mcp` | | Transport | Streamable HTTP (not SSE) | | Header | `Authorization: Bearer gum_YOUR_KEY` | ## Check the connection Ask the agent "Who am I on Gumball?" It calls the `whoami` tool and answers with your name, your role, and the shows or campaigns you can reach. If the connection fails: - **`unauthenticated`:** the header is missing or the key is mistyped. Check for a space or a line break pasted with the key. - **`key_revoked` or `key_expired`:** create a new key. - **The client asks you to sign in:** it didn't send a key, so it's signing in. Approve it on gumball.fm, or add the header if you meant to use a key. - **gumball.fm says the app can't be connected:** only an approved advertiser or creator account, signed in as itself, can connect an app. - **The agent stopped working after a month:** a sign-in connection ends after 30 days. Connect again. For what each tool does, see [MCP server](https://gumball.fm/developers/mcp).