# Use Switchbox with AI agents

> Connect an agent over MCP so it can read your flags and create new ones. It can add a flag; only you can turn one on.

Switchbox runs an [MCP](https://modelcontextprotocol.io) 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:

```bash
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](#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:

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

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

You add the SDK key for whichever environment you're running (see
[Environments & SDK keys](/docs/concepts/environments)), 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](/playground).