MCP server

What the MCP server is

The Gumball MCP server gives an AI agent the Gumball API as tools. MCP, the Model Context Protocol, is the standard that Claude, ChatGPT, and other AI clients use to call outside services.

To add the server to your client, see Connect an AI agent.

Connection details

Setting Value
Server URL https://api.gumball.fm/mcp
Transport Streamable HTTP
Authentication Sign-in (OAuth), or an API key sent as Authorization: Bearer gum_...

A client that sends no credential gets a 401 that names Gumball's sign-in server. A client that supports MCP sign-in registers itself there and sends you to gumball.fm to approve it. See Authentication.

The server keeps no session, so a client can send each request on its own. It answers clients that open with the initialize handshake and clients on the 2026-07-28 revision of the protocol.

Tools

Each tool is one API operation. The tool's name is the operation's ID, its input is the operation's parameters, and its result is the operation's response.

Tool API operation What it does
whoami GET /v1/me Who am I
search_shows GET /v1/shows Search shows
get_show GET /v1/shows/{show_id} Get a show
list_show_slots GET /v1/shows/{show_id}/slots List a show's open slots
list_my_shows GET /v1/me/shows List my shows
get_my_show GET /v1/me/shows/{show_id} Get my show
list_show_schedule GET /v1/me/shows/{show_id}/schedule List my show's schedule
list_bookings GET /v1/bookings List bookings
get_booking GET /v1/bookings/{booking_id} Get a booking
list_invoices GET /v1/invoices List a campaign's invoices
list_payouts GET /v1/payouts List a show's payouts
list_campaigns GET /v1/campaigns List your campaigns
create_campaign POST /v1/campaigns Create a campaign
get_campaign GET /v1/campaigns/{campaign_id} Get a campaign
add_cart_slots POST /v1/campaigns/{campaign_id}/cart/slots Add slots to a campaign's cart
remove_cart_slots POST /v1/carts/{cart_id}/slots/remove Remove slots from a cart
reserve_cart POST /v1/carts/{cart_id}/reserve Reserve a cart
release_reserve POST /v1/carts/{cart_id}/release Release a reserve
start_campaign_build POST /v1/campaign_builds Start a campaign build
get_campaign_build GET /v1/campaign_builds/{campaign_build_id} Get a campaign build
add_episode POST /v1/me/shows/{show_id}/episodes Add an episode
blackout_slots POST /v1/me/shows/{show_id}/slots/blackout Black out slots
reopen_slots POST /v1/me/shows/{show_id}/slots/reopen Reopen slots
set_social_post_link POST /v1/bookings/{booking_id}/social_post_links Set a social post's link
remove_social_post_link POST /v1/bookings/{booking_id}/social_post_links/remove Remove a social post's link
submit_youtube_aircheck POST /v1/bookings/{booking_id}/aircheck Submit a YouTube aircheck
list_vetting_requests GET /v1/me/shows/{show_id}/vetting_requests List vetting requests
answer_vetting_request POST /v1/me/shows/{show_id}/vetting_requests/{vetting_request_id}/answer Answer a vetting request

Every connection lists every tool. A tool the account's role can't use answers with the forbidden error, so an agent that calls whoami first knows which tools apply.

A tool that only reads data is marked read-only, so a client that asks before a write doesn't ask for it. A tool that changes data, such as reserve_cart or blackout_slots, isn't marked, and it needs a connection or key with read-and-write access. No tool purchases anything.

Results and errors

A tool result carries the operation's JSON response as structured content, and the same JSON as text for a client that reads only text.

A failed call returns the API's error JSON in a result marked as an error. For the codes, see Errors.

Limits

Tool calls count toward the same per-IP rate limit as API requests. See Rate limits and safe retries.

What the agent can reach

An agent acts as the account whose key it holds, or the account that approved it, with that key's or connection's access level. It reaches what you reach on gumball.fm and nothing else. To stop an agent, revoke its key or disconnect it on Account Settings.

Read this page as plain text.