Skip to content
NanoFlags
Start free

Tooling

AI agents (MCP)

Coding agents can work with your flags through the NanoFlags MCP server: read flags, create new ones, edit drafts and open change requests. They can never publish, approve or change policy. A person reviews every change an agent proposes, and the audit log records which agent made it.

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 canAgents cannot
Read projects, environments, flags, segments, drafts, revisions, changes and usage insightsPublish, schedule a publish, or restore a revision
Create flags and edit their settingsApprove or reject a change
Edit an environment's draft: on/off, targeting rules, default and off valuesUse the kill switch or restore a killed flag
Create and edit segmentsArchive flags or delete segments
Open a change request, add flags to it and submit it for reviewChange 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.
Example
An agent enables 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

  1. As an owner or admin, open Settings → API tokens. The AI agents section is at the top.
  2. Name the agent. The name appears on every change and audit row it makes.
  3. Limit it to the project it works on (recommended) and choose an expiry of 7, 30 or 90 days.
  4. 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:

sh
claude mcp add nanoflags --env NANOFLAGS_API_TOKEN=nf_api_… --env NANOFLAGS_PROJECT=commerce -- npx -y @nanoflags/mcp

Cursor: add the server to ~/.cursor/mcp.json or the project's .cursor/mcp.json. Other MCP clients take the same block.

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

ToolWhat it does
list_environmentsEnvironments of a project and their publishing policy.
list_flagsFlags of a project, paged.
get_flagA flag's definition and its draft per environment.
explain_flagWhat a flag is, its live and draft state everywhere, and where it is evaluated: services, SDKs and served values from usage insights.
create_flagCreate a flag. It starts off in every draft.
update_draftEdit one environment's draft: on/off, targeting rules, default and off values.
open_change_requestOpen a change for the edited flags and submit it for review.
get_change_statusStatus 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" and detail.agent_label, next to detail.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.