Model Context Protocol (MCP) Server

The Flaggr MCP Server (@flaggr/mcp-server) connects AI coding assistants—such as Claude Desktop, Cursor, VS Code Copilot, and Antigravity—directly to your Flaggr instance.

With the MCP server, AI assistants can:

• Walk new users through setup in an interactive in-chat app (Claude, Codex, ChatGPT)
• List, create, update, evaluate, and toggle feature flags
• Run rollout plans gated on browser vitals (LCP, INP, CLS), JS errors and conversion — canary vs baseline
• Work alert incidents: assign, investigate, add notes, resolve
• Read project overview KPIs, evaluation trends, flag exposure and real-user browser analytics
• Administer organizations, members, invitations, teams, flag ownership and API tokens
• Profile traces, measure real-time propagation, and inspect the audit log

New here? Follow Connect Claude, Codex & AI Assistants or the interactive guide at flaggr.dev/connect.

Remote Connector (Recommended)

Flaggr hosts a remote MCP endpoint at https://flaggr.dev/mcp — the fastest path for clients that support remote MCP servers (Claude connectors, ChatGPT connectors, Codex, Cursor). No local install, no token management — OAuth handles everything. flaggr.dev/connect has step-by-step screens for each client.

Claude Code

claude mcp add --transport http --scope user flaggr https://flaggr.dev/mcp

Then run /mcp, select flaggr and choose Authenticate.

Claude / Claude.ai

Settings → Connectors → Add custom connector → URL: https://flaggr.dev/mcp. Claude walks you through sign-in, project selection, and scoping in the browser.

Codex

codex mcp add flaggr --url https://flaggr.dev/mcp
codex mcp login flaggr

ChatGPT / generic MCP clients

Any client implementing the MCP authorization spec works: point it at https://flaggr.dev/mcp and it discovers the OAuth endpoints via /.well-known/oauth-protected-resource, self-registers via Dynamic Client Registration, and runs the authorization-code + PKCE flow.

How the flow works

Scoping

The hosted endpoint accepts both initialize-era MCP clients (through 2025-11-25) and the 2026-07-28 stateless envelope used by Cuttlefish. Modern requests carry params._meta["io.modelcontextprotocol/protocolVersion"] and matching MCP-Protocol-Version / Mcp-Method headers; tool calls and named resource/prompt reads also carry a matching Mcp-Name header. server/discover advertises the modern revision without requiring initialize. Modern results include resultType, server metadata and discovery/read caching hints; HTTP responses remain uncached. Modern batch requests are rejected, notifications receive 202, and request bodies are bounded at 1 MiB. Both paths retain the same OAuth, project and tier checks.

OAuth grants are bound to the registered client and the MCP resource https://flaggr.dev/mcp. The authorization-server metadata advertises offline_access for clients that request persistent access. Flaggr issues a refresh token with every successful grant; this auxiliary scope adds no project permissions and does not change token lifetimes. Protected-resource metadata and authentication challenges require only read. Both legacy and modern HTTP requests return finite JSON. Clients may accept application/json, application/* or */*, or omit Accept; advertising SSE is unnecessary. JSON media types are case-insensitive. Explicitly excluding JSON with q=0 still returns 406, and non-JSON request media types return 415. MCP authentication failures return X-Flaggr-MCP-Request-ID; token exchanges return X-Flaggr-OAuth-Request-ID. Server diagnostics record refusal categories and whether a refresh token was issued, without recording tokens, OAuth parameters or project scopes. Code exchange requires the registered redirect_uri; refresh requires the issuing client_id. When a client supplies resource, it must identify this endpoint and match the consented resource. For older clients that omit it, Flaggr binds the grant to its own MCP endpoint. A mismatched refresh request is rejected without consuming the legitimate connection's token. Token responses are never cached.

Deployments upgrading from earlier versions must apply 054_mcp_oauth_resource.sql before starting the new server. The additive migration binds existing production grants to this endpoint without changing their projects, permissions, expiry or secrets. Independent runtime and scanner grants with identical consent remain supported.

For hosted transport failures, server logs record a protocol_rejected phase with the X-Flaggr-MCP-Request-ID returned to the client. It includes elapsed time, HTTP status, a fixed rejection category (for example invalid_jsonrpc or unsupported_protocol_version), and header presence/compatibility indicators. Unsupported version values, session IDs, credentials, request bodies and raw SDK errors are not included. A fast HTTP rejection and a client-side timeout are separate observations; correlate them before attributing a scanner failure to a particular request.

During consent you pick which projects the connector can access and one of three access levels for the connection. That level is the most any project can get. Each selected project can then be given a lower level on the same screen:

Rollout status reads (get_canary_status, list_rollout_plans, get_rollout_plan) let the engine progress due stages, including rollback and configured notifications, so they require write access. check_site_guardrails also requires write access because it can execute mitigation. Use get_connection for a passive connection check.

Tools above the connection's level are not advertised to the client at all. The API enforces each project's access on every request to that project: a project at read gets 403 on any change there, and a project below admin gets 403 on its member, team, token and settings routes. Creating an API token, a flag trigger or a share link, listing a project's API tokens and inviting a project member need admin on that project. Organization-level changes need admin on every selected project of that organization. Creating an organization needs admin at the connection's level, and creating a project needs that and, in an organization that owns selected projects, admin on each of them (403 "connector token lacks the admin scope for every project of this organization"). Deleting a project or organization is never available to a connector. Administration is opt-in on the consent screen even when a client requests it.

Project scope is enforced server-side on every tool call — a token for project-a gets 403 on project-b, list_projects only returns consented projects, and scope survives token refresh. When an admin connector creates a project with create_project, that project joins the token's scope automatically, at the connection's level.

Organization-level tools work only in organizations that own at least one of the connector's consented projects. A connector can create a project only in such an organization, or in a brand-new organization you created that has no projects yet: after create_organization, create a project in the new organization with create_project before managing the organization. Anywhere else it gets 403 "connector token is not scoped to this organization". Connectors can never change project or organization ownership (granting or removing owner); use the dashboard.

Latest access wins. A changed approval from the same OAuth client (the same client_id) replaces its grants with different stored scopes or project selections, so a narrower approval cannot leave broader access in use. Exact stored consent matches can coexist, such as a runtime connection and a publication scanner: each gets independent access and refresh tokens, and authorizing one does not invalidate the other. Creating a project through the connector also changes its allowlist and invalidates that client's other grants with a different project selection. Explicitly disconnect the client on flaggr.dev/connect to revoke all its grants rather than relying on an identical reauthorization. An assistant that registers a new client when it reconnects appears as a separate connection; disconnect the old client there too if it is no longer needed.

Access errors

A connector gets a 403 that names the access it lacks. Reconnect and raise that access on the approval page:

Project API tokens and personal access tokens get a 403 that names what they lack: more access (for example read-only or lacks admin access), or, for a project API token whose scopes don't name the service, environment or flag of the request, API token scopes don't cover this resource. Create a token with the access or scopes the request needs. Reconnecting applies only to connectors.

Revocation

Disconnect any assistant from flaggr.dev/connect, which lists each connected client with its access level, each project's access, its projects and its last use. Disconnect revokes all the client's grants and also voids approvals it hasn't exchanged for a token yet. POST /api/oauth/revoke revokes the individual grant identified by its supplied access or refresh token. Tokens are hashed at rest and checked on every request, so revocation is immediate.

Local Stdio Setup

Use the local server with a personal access token (fgp_… — every project you can access, capped by its tier; create one under Profile → Personal access tokens), a project API token (fgr_… — one project), or the credentials flaggr login saved.

1. Claude Desktop

Add @flaggr/mcp-server to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "flaggr": {
      "command": "npx",
      "args": ["-y", "@flaggr/mcp-server@latest"],
      "env": {
        "FLAGGR_API_URL": "https://flaggr.dev",
        "FLAGGR_API_TOKEN": "fgp_your_token_here"
      }
    }
  }
}

Tip: If you have already authenticated using the Flaggr CLI (flaggr login), the MCP server will automatically discover your credentials from ~/.flaggr/config.json. You can omit FLAGGR_API_TOKEN.

Use @flaggr/mcp-server 0.3.0 or later: earlier versions can run shell commands taken from a crafted url passed to the login tool. @latest makes npx fetch the newest release from npm (npm view @flaggr/mcp-server version shows which that is); with no version, npx can keep running an older copy from its cache. Until npm view @flaggr/mcp-server version prints 0.3.0 or later, @latest installs an earlier version: use the remote connector instead.

2. Cursor IDE

Add to your project's .cursor/mcp.json or Global Cursor Settings:

{
  "mcpServers": {
    "flaggr": {
      "command": "npx",
      "args": ["-y", "@flaggr/mcp-server@latest"],
      "env": {
        "FLAGGR_API_URL": "https://flaggr.dev",
        "FLAGGR_API_TOKEN": "fgp_your_token_here"
      }
    }
  }
}

Authentication Methods

The Flaggr MCP server supports three authentication methods:

1. Auto-Discovery via Flaggr CLI: Reads ~/.flaggr/config.json minted by flaggr login. Zero configuration required.
2. Interactive OAuth via login Tool: Prompt the agent: "Log in to Flaggr". The agent calls the login tool, opening your browser to authorize. Choose All my projects on the authorization page for a personal access token (write tier, 90 days), or One project for a project API token. The tool sends a one-time state to the sign-in page and accepts only the browser callback that returns it. Any other request to its localhost port is ignored, so a web page can't log the server into a different account. The sign-in page hands over the token in a form POST, never in a URL, so it stays out of your browser history. The tool refuses a token sent in the URL by an older Flaggr server and asks you to revoke it. The tool's url must be an http(s) server base URL without user name, password, query or fragment; the browser is opened without a shell. logout forgets the token on this machine (memory and ~/.flaggr/config.json) but doesn't revoke it — revoke it under Profile → Personal access tokens, or in the project's Settings → API tokens for a project API token.
3. Direct Environment Variable: Set FLAGGR_API_TOKEN — a personal access token (fgp_…) or a project API token (fgr_…) — in your MCP configuration.

get_connection shows which credential and tier the server is using. The stdio server reads the same answer from /api/users/me and hides the tools its token can't use.

Personal access tokens (fgp_…) work everywhere except flag evaluation and creating credentials. With one, the stdio server also hides evaluate_flag, trace_flag_evaluation, watch_flag_updates, measure_round_trip, record_bandit_reward, create_api_token, rotate_api_token, invite_project_member and invite_org_member. Read-tier tokens can't make changes: the API accepts only GET requests and the read-only POSTs (explain, simulate, advice, code references, cohort evaluation) from them. Read-tier tokens keep explain_flag_evaluation, simulate_flag_targeting and evaluate_cohort_membership. Evaluate with a project API token (SDK key), and create API tokens and invitations in the dashboard.

Project API tokens (fgr_…) act only inside their project, capped by their scopes: project, service, environment or flag rules, each read, write or admin. A legacy whole-project token is capped by its Read / Write / Delete permissions (Delete counts as the admin tier). With one, the stdio server also hides the tools project tokens can never use: create_api_token, rotate_api_token, invite_project_member, invite_org_member, create_project, create_organization, every organization tool except get_organization, list_org_projects and list_organizations, and the member, invitation and team tools (add_project_member, update_project_member, remove_project_member, list_project_invitations, revoke_project_invitation, create_team, update_team, delete_team). delete_flag needs admin access to the flag (an admin scope covering it, or the Delete permission on a legacy token), so read and write tokens — including the read+write tokens flaggr login mints — don't see it; the other delete tools only need Write. A 403 from a token names what it lacks: create a token with that access or with the scopes the request needs (reconnecting only applies to connectors). Manage members and teams with a personal access token or a connector, and create tokens and invitations in the dashboard (or with an admin connector).

The Flaggr app (MCP Apps)

open_flaggr opens an interactive view (ui://flaggr/console, text/html;profile=mcp-app) in hosts that support MCP Apps — Claude, Codex and ChatGPT. New connections get a setup checklist with a screen per stage (connect → project → service → first flag → SDK → browser analytics); finished projects get a home with KPIs, flags and suggested prompts. In Codex, the tool's global entrypoint lists Flaggr under Explore, where you can Pin to sidebar.

The view is a self-contained bundle (no remote assets or network access of its own). Every read and write goes through the host bridge to this server; before any change it re-reads get_connection and stops if the server, account or access level changed. Its access hints follow the credential: a connector is told to reconnect and allow more access, while a personal access token or project API token is told to create a token with the tier it needs (Profile → Personal access tokens, or the project's settings → API tokens). Prompts are only sent to the chat, and context only shared, when you click.

Clients without MCP Apps get the same checklist from get_onboarding_status. Both offer to create a project only to credentials that can: dashboard sessions, admin connectors and admin personal access tokens (never project API tokens).

Tool Catalog

164 tools, grouped by area; the local stdio server adds three sign-in tools (167 in all). Access is the minimum connector level that can see the tool. The local stdio server applies the same tiers to its own token — a connector's scope, or the tier of a project API token or personal access token, read from /api/users/me at startup and again after login/logout — and hides the tools that kind of token can never use (see Authentication Methods). A connector narrowed on some projects shows the stdio server the tools of the connection's tier, as the hosted connector does (/api/users/me reports the connection's tier), and the API refuses what a project's lower access doesn't allow (403 "… in this project"). With no token, or no answer within 3 seconds, it shows every tool. Project roles still apply.

Setup & connection

Directory

Organizations, projects & members

Connectors manage only organizations that own one of their consented projects, and create projects only there or in a brand-new organization (see Scoping). Connectors and project API tokens can never change ownership (granting, changing or removing owner) — use the dashboard, or a personal access token created with owner actions.

Teams & flag ownership

API tokens

Services & code references

Code searches use the GitHub repository connection saved by a project administrator in Settings → GitHub. Neither code-reference tool accepts a GitHub credential. Missing configuration, expired credentials and inaccessible repositories produce actionable errors; reconnect in Flaggr rather than putting credentials in chat.

Flags, evaluation & tracing

Targeting, overrides & cohorts

Rollout plans & releases

start_canary_rollout is a one-call shortcut over these plans: it creates and starts a canary-strategy plan whose guardrails are the flag's pre-canary error rate and p99 plus the allowed deltas (never below 2% / 100 ms), and the engine advances it every 5 minutes. get_canary_status, advance_canary_stage and abort_canary_rollout act on the flag's live plan. The gates count only evaluations served by flaggr.dev (api.flaggr.dev and SDK-local evaluation record none), so a stage with too few of them (minSampleSize, default 200) holds until it is advanced with force. Use create_rollout_plan when you need approval gates, ring cohorts or RUM guardrails.

get_rollout_analysis also reports what the RUM trust filters kept out of the stage's browser SLIs, for the canary and the baseline: sessions and events marked untrusted (sent from outside the Site's domain), and sessions and events over a cap. The caps are 5 sessions per client per arm, and 10 samples of each web vital (and of rage and dead clicks) per session. It also reports counted sessions that have no client key (rows written before the ingest identified clients, or by an ingest that couldn't), which the per-client cap can't apply to.

Plan tools turn the API's coded refusals into next steps. BUSY, PLAN_CHANGED and the 503s (APPROVAL_CHECK_UNAVAILABLE, RULE_WRITE_FAILED, UNAVAILABLE) changed nothing and can be retried in a moment. ROLLOUT_IN_PROGRESS names the flag's live plan: cancel it with cancel_rollout_plan or let it finish. PLAN_AWAITING_APPROVAL means the draft's start request is open. While it is pending, withdraw it with DELETE /api/projects/{id}/change-requests/{changeRequestId} (the requester, or an admin of the plan's service and environment) or Withdraw request on the plan's page in the console, then start the plan again. Once it is approved but not applied, apply it with POST /api/projects/{id}/change-requests/{changeRequestId}/apply (an admin of the plan's service and environment; it starts the plan exactly as approved), or withdraw it with the same DELETE; the plan's page offers Approved — apply and Withdraw request for it. A request past its 7-day expiry can only be withdrawn: applying it answers 409 CHANGE_REQUEST_EXPIRED and retires it. start_rollout_plan on such a draft answers START_APPROVED with the same two choices. ROLLOUT_RULE_PRESENT means a failed, rolled-back or cancelled plan's rule still serves: clear it with abort_canary_rollout and the plan's id as pipelineId, then delete the plan. ROLLOUT_RULE_SHADOWED means a rule ahead of the plan's serves everyone (no conditions or condition groups, or only the match-all condition, no schedule, and 100% or no percentage), such as a rule an earlier plan left at 100%, so the plan's rule would reach nobody. The error names each such rule's remove_targeting_rule call: remove the rule, or give it conditions, a schedule or a percentage below 100, then start the plan again. The check comes before any approval is requested. create_rollout_plan needs an existing flag (FLAG_NOT_FOUND) whose key matches [A-Za-z0-9_][A-Za-z0-9._-]*. EXPERIMENT_RUNNING comes back as the API's own message, which names the running or paused experiment on the flag: end it with end_experiment before starting a plan or canary there (experiments have no environment, so this applies in every environment).

Experiments & bandits

Bandits are experimental. A bandit experiment is held in one server instance's memory, not in the database: a call that reaches another instance, or comes after a restart, gets 404 (Bandit experiment "…" not found), and the trials recorded so far are lost. For a test that has to last, use create_experiment, which is stored.

Alerts & incidents

Unless the credential can manage the owner's settings (admin tier, and an admin or owner role in the project or organization), channel secrets come back as [redacted]. Pass [redacted] back unchanged to keep a stored secret. Changing where a channel sends it — its URL, recipients or type — while keeping the placeholder needs that same access; otherwise pass the real secret again. Alert rules are evaluated every 5 minutes from the evaluations flaggr.dev records, and new rules can't use the legacy grpc_errors and cache_hit_rate conditions; see Alerting.

Overview & browser analytics

Issues & server telemetry

Flag analytics & RUM impact

Sites

create_site: the server generates the site ID (site_…), which goes in the browser analytics tag, <script src="https://cdn.flaggr.dev/a.js" data-site-id="site_…" defer></script> (get_site and create_site print the tag with the site's ID, and the CSP origins it needs); slug is an optional label unique within the service. A reserved slug is refused with 400 SITE_SLUG_RESERVED and a duplicate with 409 SITE_SLUG_TAKEN. The siteId parameter of the other site tools is that ID, not the slug. check_site_guardrails lists blocked mitigations with their code (APPROVAL_REQUIRED, ROLLOUT_IN_PROGRESS, FORBIDDEN, BUSY). get_sdk_analytics defaults projectId to the configured project when serviceId is omitted.

Health

Audit & history

Local server only (stdio)

The local server adds three tools for its own sign-in; the hosted connector signs in with OAuth instead.

With a project API token, the server makes that token's project its default project for the session. A project token reaches only its own project, so this replaces default_project_id from ~/.flaggr/config.json in memory (the file isn't changed), and the server logs the switch to stderr.

MCP Resources

Agents can read context directly via dynamic resource URIs:

• ui://flaggr/console — The Flaggr app (MCP Apps HTML resource)
• flaggr://auth/status — Active token preview, current project, and connection status
• flaggr://projects — List of all accessible projects
• flaggr://project/{slug}/flags — Feature flags in a project
• flaggr://flag/{key}/health — Flag health status
• flaggr://flag/{key}/toggle-impact — Post-toggle safety and drift analysis
• flaggr://site/{siteId} — Site details, domain and linked flags

MCP Prompts

The server provides pre-packaged prompt templates for complex flag management tasks:

verify_toggle_safety

Prompts the agent to inspect the safety of a recent flag toggle:

Verify post-toggle safety for flag "checkout-v2" in service "web-app".

The agent calls get_flag_toggle_impact, analyzes before/after error rates and P99 latencies, and proposes rolling back if health is degraded.

gradual_rollout

Guides an agent through a staged percentage rollout: add_targeting_rule without conditions (a rule that matches everyone) at rolloutPercentage: 5, then update_flag raising that rule's percentage (5% → 25% → 50% → 75% → 100%), checking get_flag_health at each step before advancing. Data planes from before Flaggr 0.5.0 (https://api.flaggr.dev until it is updated) match a rule without conditions to nobody, so the prompt also tells the agent to give the rule the match-all condition (targetingKey not_equals __flaggr_rollout_match_all__), which serves everyone on every plane.

ab_test_setup

Designs an experiment with treatment and control variants, sets traffic allocation, and configures outcome metrics.

targeting_strategy

Designs a targeting strategy for a flag from user attributes and a stated goal.

Autonomous Agent Workflow Examples

Example: Verifying a Production Flag Toggle

Ask your assistant:

"Check if toggling new-payment-engine in production was safe or if there was any error drift."

The assistant invokes:

{
  "tool": "get_flag_toggle_impact",
  "arguments": {
    "flagKey": "new-payment-engine",
    "serviceId": "checkout-service",
    "environment": "production"
  }
}

The MCP server responds with:

============================================================
FLAG TOGGLE IMPACT REPORT: new-payment-engine
============================================================
Status: [HEALTHY]
Latest Toggle Event:
  - Transition: false -> true
  - Actor:      lead-dev@flaggr.dev
  - Timestamp:  2026-09-12T08:00:00.000Z
  - Propagation Latency: 38ms
 
Before vs After Comparison (±30m window):
┌──────────────────────┬─────────────┬─────────────┬────────────────┐
│ Metric               │ Before      │ After       │ Delta / Ratio  │
├──────────────────────┼─────────────┼─────────────┼────────────────┤
│ Evaluations          │ 2450        │ 2480        │ 1.01x          │
│ Errors               │ 1           │ 1           │ +0             │
│ Error Rate           │ 0.04%       │ 0.04%       │ +0.00%         │
│ Avg Latency          │ 1.35ms      │ 1.34ms      │ -              │
│ P99 Latency          │ 3.80ms      │ 3.75ms      │ -0.05ms        │
└──────────────────────┴─────────────┴─────────────┴────────────────┘
 
Automated Recommendation:
Healthy: Post-toggle metrics are stable with no significant error or latency regression.
============================================================

The assistant summarizes the findings and confirms the deployment is stable.

Next Steps

• REST API Reference — Core Flaggr REST endpoints
• Personal Access Tokens — Account-level tokens for the local server, the CLI and Terraform
• Flag Health Guide — Post-toggle safety and drift diagnostics
• OpenFeature SDKs — Evaluate flags in your application code