MCP Server

The Featureflip MCP server (@featureflip/mcp) lets AI coding assistants and autonomous agents manage feature flags through the Management API: create and toggle flags, adjust targeting and rollouts, and find stale flags ready for cleanup — without leaving the editor.

It runs as a local process over stdio via npx, so there’s nothing to deploy: your agent starts it, talks to it over the Model Context Protocol, and it calls the Management API on your behalf using whatever token you give it.

Installation

You’ll need an API token first — see Authentication below. Once you have one, add the server to your MCP client.

Claude Code

claude mcp add featureflip -e FEATUREFLIP_TOKEN=ffp_your_token -- npx -y @featureflip/mcp

Cursor / Cline / generic JSON config

Most other MCP clients (Cursor, Cline, and anything that reads a standard MCP config file) use a JSON block like this:

{
  "mcpServers": {
    "featureflip": {
      "command": "npx",
      "args": ["-y", "@featureflip/mcp"],
      "env": { "FEATUREFLIP_TOKEN": "ffp_your_token" }
    }
  }
}

Both forms launch the same package: npx -y @featureflip/mcp. The -y flag skips npm’s install confirmation prompt, which matters because most MCP clients invoke the command non-interactively.

Authentication

The MCP server authenticates the same way the Management API does — with a bearer token passed via the FEATUREFLIP_TOKEN environment variable. There are two token types:

• Personal token (ffp_...) — create one under Settings → API Tokens in the dashboard. It acts as you, carrying your role in every organization you belong to. This is the right choice for interactive editor use (Claude Code, Cursor) where you want the agent’s changes attributed to you.
• Service token (ffs_...) — create one under Organization Settings → Service Tokens. It’s a machine identity scoped to a single organization, and the right choice for CI or unattended agents.

See Authentication for the full walkthrough of token types, roles, and error handling — the MCP server inherits all of it. A token below the required role for a write returns the same 403 forbidden you’d see from a raw API call.

Configuration

Env var	Required	Default	Purpose
FEATUREFLIP_TOKEN	yes	—	ffp_/ffs_ API token
FEATUREFLIP_API_URL	no	https://api.featureflip.io	API base URL
FEATUREFLIP_ORG	no	auto	Org slug (needed only for multi-org personal tokens)

Most setups only need FEATUREFLIP_TOKEN. Set FEATUREFLIP_API_URL if you’re pointing at a self-hosted or non-default deployment. Set FEATUREFLIP_ORG if your personal token belongs to more than one organization — without it, the server exits at startup with an error listing the org slugs it can see (it can’t prompt you interactively) and you re-run with FEATUREFLIP_ORG set to one of them.

Tool reference

The server exposes 19 tools. Read-only tools are always safe to call; destructive tools change or remove existing state and should be used deliberately (most agent clients will ask for confirmation before running them). Non-destructive writes create new state without touching anything existing.

Read-only

Tool	What it does
list_projects	List projects in an organization
list_environments	List environments in a project
list_segments	List reusable user segments in a project
get_segment	Get a single segment’s rules
list_flags	List feature flags in a project
get_flag	Get a single flag’s configuration
flag_status	Cross-environment view of a flag’s enabled state, strategy, default variation, and prerequisites per environment
get_targeting	Get a flag’s current targeting rules in one environment — read before you update_targeting
find_stale_flags	Find flags that look like cleanup candidates

Non-destructive writes

Tool	What it does
create_flag	Create a new feature flag (starts disabled in every environment)
update_flag	Update a flag’s name, description, or metadata
restore_flag	Restore an archived flag
wrap_feature	Create a flag and return an SDK snippet to wrap your code with it

Destructive

Tool	What it does
delete_flag	Permanently delete a flag
archive_flag	Archive a flag
toggle_flag	Enable or disable a flag in an environment
update_flag_environment_config	Change a flag’s per-environment configuration
update_targeting	Replace a flag’s targeting rules, conditions, and rollout percentage wholesale — read the current rules first with get_targeting
manage_variation	Add, update, or remove a flag’s variations

Example agent workflows

Wrap new code in a flag

Ask the agent to gate a new feature behind a flag. It calls wrap_feature, which creates the flag (disabled everywhere, as all new flags are) and returns a code snippet using the SDK for your project’s language — the agent applies that snippet directly to your working tree. Once you’re ready to test it, ask the agent to enable it in dev: it calls toggle_flag for the dev environment. The flag stays off in every other environment until you say otherwise.

Ramp a rollout

To gradually roll out a flag that’s already live, ask the agent to ramp it: it calls update_targeting with rolloutPercentage set to 10, then later 50, then 100 as you gain confidence — each call replaces the previous percentage rather than stacking. Once the flag has been at 100% for a while, it’s a candidate for cleanup — find_stale_flags will start surfacing it.

Clean up shipped flags

Periodically ask the agent to find cleanup candidates. It calls find_stale_flags, which returns flags that have been fully rolled out or unchanged for a long stretch. find_stale_flags checks whether every environment is enabled, not whether a per-rule percentage ramp has actually reached 100% — confirm the rollout is complete before removing. For each one you confirm, the agent calls delete_flag and removes the corresponding conditional from your code — leaving a single code path where the flag used to be.

Notes

• Flag evaluation is not exposed over MCP — use the SDKs in application code. The MCP server manages flag configuration, not runtime evaluation.
• wrap_feature returns a snippet for you or your agent to apply; it never edits files on its own.
• Every mutation is audit-logged and attributed to the token that made it, same as a direct API call.
• Requests are rate-limited per token. Errors carry machine-readable hints (did_you_mean, next_actions) so an agent can recover without human intervention — for example, a typo’d flag key suggests the closest match, and a 403 on a locked action points at what to try next.