Use Switchbox with AI agents

Switchbox runs an MCP server, so an AI coding agent can read your flags and create new ones without you leaving your editor.

The point of it is one workflow:

"Put this behind a flag."

The agent creates the flag, wires the SDK into your code, and tells you the flag key. The flag arrives off in every environment, and you turn it on from the Switchbox dashboard when you're ready. No agent can do that part.

Connect it

There's nothing to install. The server is an HTTP endpoint:

claude mcp add --transport http switchbox https://api.switchbox.dev/mcp

Then authenticate. Your agent opens Switchbox in your browser, you sign in the way you always do, and you approve the connection on a consent screen that lists exactly what it will be able to do. Control returns to your terminal.

You never paste a token. There's no API key to create, copy, or leave in a config file, which also means there's nothing to leak and nothing to remember to rotate. The connection is a grant tied to your account, and you can end it at any time (see Disconnecting).

Other MCP clients work the same way if they support remote servers with OAuth. Point them at https://api.switchbox.dev/mcp.

What the agent can do

Read

• Your projects, and the environments in each one
• Every flag with its per-environment state: on or off, rollout percentage, the values it serves, and its targeting rules with segments already expanded
• Evaluation analytics per flag, and the audit history of who changed what

Write

• Create a new flag. That's the whole list.

Never, at any permission level

• Turn a flag on or off
• Change targeting, rollouts, or values on a flag that already exists
• Rename or delete anything
• Create or delete projects, environments, teams, or members
• Read an SDK key

That last one is deliberate: an SDK key reads a whole environment's config from the CDN, permanently, outside every check in this list. Handing one to an agent would turn a revocable connection into a forever one, so no tool returns one. You paste the key yourself, once, the same way you would for any SDK.

The one rule worth knowing

An agent can add a flag. Only a human can turn one on.

This isn't a setting you enable or a checkbox you're trusted to leave alone. There is no permission in Switchbox that lets an API token change whether a flag is on, so it can't be granted by mistake, talked into existence by a persuasive prompt, or turned on by a compromised agent. The kill switch is yours.

A flag an agent creates changes nothing for anyone until you act. That's what makes creating one safe enough to need no extra ceremony.

Telling the agent which project

The first time, the agent asks which Switchbox project the codebase belongs to, then writes its answer to switchbox.json at the root of your repo:

{
  "project": "ed294d0d-6e5d-45ad-a401-83e84aed9f29",
  "projectName": "Checkout service"
}

Commit it. It's not a credential, it's a pointer, and it means you're never asked again. Every agent that works in the repo reads the same file.

A full pass

Working on a feature, you say:

Put the new announcement banner behind a flag.

The agent creates landing_announcement_banner, boolean, off everywhere, and edits your code to check it:

if switchbox.enabled("landing_announcement_banner", user):
    render_banner()

You add the SDK key for whichever environment you're running (see Environments & SDK keys), and the banner stays hidden, because the flag is off.

Then you open the dashboard, find the flag, and turn it on for your local environment. The banner appears. Turn it off, it goes. Production is a separate switch you flip when you're ready, and neither one was ever the agent's to touch.

Who the change is recorded as

Every change an agent makes is attributed to you, with the agent named alongside:

Ignat Petrov, via Claude Code

The person who authorized the connection is the actor, because they are the one accountable. The client is recorded as a separate fact so you can tell at a glance which changes came through an agent, in both the activity feed and a flag's audit history.

Disconnecting

Go to Profile → Connected clients. Every agent you've authorized is listed with what it can do, when it connected, and when it was last used.

Disconnect ends it immediately. Every request re-checks the connection, so access stops on the agent's very next call rather than whenever a token happens to expire.

It's worth a look now and then. A client names itself, so the name on that list is whatever the client said it was, and it's only trustworthy to the extent you trusted the thing you connected.

What it deliberately can't tell you

The server describes flag configuration. It cannot tell you what a specific user would get, and no tool will.

Evaluation lives in the SDKs, where it has exactly one implementation per language and is verified to produce identical results across all of them. A second implementation answering "what would user X see?" over an API would be a second answer to a question that must only have one. To evaluate a flag, use an SDK, or the Playground.