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.