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:

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

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:

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:

{
  "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:

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

Read this page as plain text.