Tooling
AI agents (MCP)
On this page
Agents propose, people approve
An agent works with an AI-agent token, a Management API token with a fixed, narrow set of permissions and a name you choose, such as Claude Code on laptop-x. Like every API token it acts as the person who created it, with that person's current role. On top of that, NanoFlags refuses everything except proposing, and it does so in its database, below the API: no endpoint, old or new, can publish, approve or change settings for an agent.
What an agent can and cannot do
| Agents can | Agents cannot |
|---|---|
| Read projects, environments, flags, segments, drafts, revisions, changes and usage insights | Publish, schedule a publish, or restore a revision |
| Create flags and edit their settings | Approve or reject a change |
| Edit an environment's draft: on/off, targeting rules, default and off values | Use the kill switch or restore a killed flag |
| Create and edit segments | Archive flags or delete segments |
| Open a change request, add flags to it and submit it for review | Change environment policies, permissions, members, API tokens, SDK keys, integrations, billing or organization settings |
A refused request answers 403 with the error code AGENT_FORBIDDEN and a message telling the agent to open a change request instead.
The approval rule
- Work an agent proposes always needs an independent approval by a person before it is published, even in environments that do not require approval. This covers a change opened by an agent and any draft that holds edits an agent made since the environment was last published.
- Where the environment requires more approvers, that number applies; otherwise one approval is needed.
- The normal independence rules apply: the author of a change and anyone who edited its draft cannot approve it. The agent acts as the token's owner, so the owner of an agent token can never approve that agent's work. Another owner or admin must.
- Publishing stays a person's action, in the dashboard or with a standard API token.
checkout-v2 for pro customers in the Staging draft and opens a change. Staging does not require approval, but publishing now needs a change approved by someone other than the token owner. Maya approves it; Omar publishes it.Create an agent token
- As an owner or admin, open Settings → API tokens. The AI agents section is at the top.
- Name the agent. The name appears on every change and audit row it makes.
- Limit it to the project it works on (recommended) and choose an expiry of 7, 30 or 90 days.
- Copy the token. It is shown once; NanoFlags stores only its hash. Revoke it in the same place at any time.
Connect your agent
The MCP server runs on the developer's machine (Node 20 or later) and reads NANOFLAGS_API_TOKEN, optionally NANOFLAGS_PROJECT (the default project key) and NANOFLAGS_BASE_URL.
Claude Code:
claude mcp add nanoflags --env NANOFLAGS_API_TOKEN=nf_api_… --env NANOFLAGS_PROJECT=commerce -- npx -y @nanoflags/mcpCursor: add the server to ~/.cursor/mcp.json or the project's .cursor/mcp.json. Other MCP clients take the same block.
{
"mcpServers": {
"nanoflags": {
"command": "npx",
"args": ["-y", "@nanoflags/mcp"],
"env": { "NANOFLAGS_API_TOKEN": "nf_api_…", "NANOFLAGS_PROJECT": "commerce" }
}
}
}Keep the token out of version control: in a shared configuration file, reference an environment variable instead of the value.
Tools
| Tool | What it does |
|---|---|
list_environments | Environments of a project and their publishing policy. |
list_flags | Flags of a project, paged. |
get_flag | A flag's definition and its draft per environment. |
explain_flag | What a flag is, its live and draft state everywhere, and where it is evaluated: services, SDKs and served values from usage insights. |
create_flag | Create a flag. It starts off in every draft. |
update_draft | Edit one environment's draft: on/off, targeting rules, default and off values. |
open_change_request | Open a change for the edited flags and submit it for review. |
get_change_status | Status and approvals of a change. |
There is no tool to publish, approve or kill, by design.
Audit and identity
- Every audit row written with an agent token carries
detail.actor_type = "agent"anddetail.agent_label, next todetail.via = "api_token"and the token id. The actor stays the token's owner: a person is always accountable. - The activity log, the changes list and each change show via agent <name>.
- A change opened by an agent keeps that fact permanently, even after the token is revoked.
Plans
Agent tokens are available on every plan, and agents can never publish, approve or change policy on any plan. The mandatory independent approval of agent work is part of required approvals, a Team feature (Team, Scale and Enterprise). On Explore and Solo, a person reviews the agent's draft or change and publishes it; the dashboard explains this next to the change. See Plans and limits.
Management API
The MCP server is a thin wrapper over the Management API; agents and scripts can use the API directly with the same token. GET /api/v1/token answers kind: "agent" and agentLabel, and changes opened by an agent carry openedByAgent.