Use Gumball with Claude, ChatGPT and AI agents

Gumball speaks MCP (Model Context Protocol), so AI assistants and agents can ring it, set its volume and mute it, just by asking: “ring the Gumball when the deploy is done”, “play sound 5 when the tests pass”, “mute the office Gumball until tomorrow”.

1. Make a token

Sign in to your Gumball account and find AI agents & command line. Give the token a name (“Claude”) and click Make a token. The page then shows everything below, ready to copy, with your token already in it. Make one token per app, so you can cut one off without touching the others.

2. Connect your assistant

Claude (claude.ai and the desktop app)

Settings → Connectors → Add custom connector. Name it Gumball and paste your MCP address:

https://app.getgumball.com/mcp/gb_your_token

ChatGPT

Settings → Apps & Connectors → turn on developer mode, then Create a connector with the same MCP address.

Claude Code

claude mcp add --transport http gumball https://app.getgumball.com/mcp --header "Authorization: Bearer gb_your_token"

Cursor, VS Code and other MCP apps

Add a server with the address https://app.getgumball.com/mcp and the header Authorization: Bearer gb_your_token. In Cursor’s mcp.json:

{ "mcpServers": { "gumball": { "url": "https://app.getgumball.com/mcp", "headers": { "Authorization": "Bearer gb_your_token" } } } }

What agents can do

• list_gumballs: your Gumballs and whether they are online
• ring_gumball: spin and play a sound (sound 0 is light only)
• play_random_sound: a random sound in a range
• set_volume: from 0 to 21
• mute_gumball / unmute_gumball: ignore notifications, or not

With several Gumballs, agents pick one by its name, so give each a name on its page. Agents can’t change your WiFi, firmware or passwords.

Command line

For scripts, CI and the terminal:

npx getgumball login gb_your_token

npx getgumball ring --sound 3

Also list, random 1 15, volume 12, mute and unmute. In CI, skip the login and set GUMBALL_TOKEN:

GUMBALL_TOKEN=gb_your_token npx getgumball ring --sound 5

Good to know

• Treat a token like a password: anyone who has it can ring your Gumballs. Delete it on your account page to cut it off straight away.
• Every agent action is in your Gumball’s activity list, with the token’s name.
• Up to 30 actions a minute per token.
• Running your own server? Use its address instead of app.getgumball.com, and --server with the command line.

👉 Prefer plain webhooks? See Connecting apps.