@flagdeck/mcp-server

Model Context Protocol (MCP) server for Flagdeck - enables AI agents like Claude, Cursor, and Windsurf to manage feature flags directly.

What is This?

This is an MCP server that allows AI coding assistants to:

• ✅ Create, read, update, and delete feature flags
• ✅ Evaluate flags for specific users/contexts
• ✅ Manage projects and environments
• ✅ Use natural language to create/update flags ("Create a dark mode flag for premium users")
• ✅ All from within your editor or CLI

Quick Start

Installation

npm install -g @flagdeck/mcp-server

Configuration

Set up your environment variables:

export FLAGDECK_API_KEY=your-api-key
export FLAGDECK_API_URL=https://api.flagdeck.com  # optional, defaults to http://localhost:3008
export FLAGDECK_PROJECT_ID=your-project-id  # optional, can be provided per-request
export FLAGDECK_ENVIRONMENT=production  # optional, defaults to production

Running the Server

flagdeck-mcp

The server runs on stdio and communicates via the Model Context Protocol.

Usage with AI Assistants

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "flagdeck": {
      "command": "flagdeck-mcp",
      "env": {
        "FLAGDECK_API_KEY": "your-api-key",
        "FLAGDECK_API_URL": "https://api.flagdeck.com",
        "FLAGDECK_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Then in Claude Desktop:

You: "Create a dark mode feature flag"
Claude: *uses create_flag tool* Done! I've created the dark-mode flag.

You: "Roll it out to 25% of users"
Claude: *uses update_flag tool* Updated! Now rolling out to 25% of users.

You: "Check if it's enabled for [email protected]"
Claude: *uses evaluate_flag tool* Yes, it's enabled for that user.

Cursor IDE

Add to .cursor/mcp.json:

{
  "servers": {
    "flagdeck": {
      "command": "flagdeck-mcp",
      "env": {
        "FLAGDECK_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to Windsurf MCP configuration:

{
  "servers": {
    "flagdeck": {
      "command": "npx @flagdeck/mcp-server",
      "env": {
        "FLAGDECK_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Project & Environment Management

list_projects

List all projects accessible to your API key.

Example:

"Show me all my projects"

get_project

Get details of a specific project.

Parameters:

• projectId (optional): Project ID

list_environments

List all environments in a project.

Parameters:

• projectId (optional): Project ID

Flag Management

list_flags

List all feature flags in a project.

Parameters:

• projectId (optional): Project ID
• status (optional): Filter by status (active/inactive/archived)
• search (optional): Search by name or key

Example:

"Show me all active flags"
"List flags containing 'checkout'"

get_flag

Get details of a specific flag.

Parameters:

• projectId (optional): Project ID
• flagId OR flagKey: Flag identifier

Example:

"Show me the dark-mode flag"

create_flag

Create a new feature flag.

Parameters:

• projectId (optional): Project ID
• key (required): Unique flag key
• name (required): Human-readable name
• description (optional): Description
• valueType (required): boolean | string | number | json
• defaultValue (required): Default value
• targetingRules (optional): Array of targeting rules
• rolloutPercentage (optional): Rollout percentage (0-100)

Example:

"Create a flag called 'new-checkout' with 25% rollout"

update_flag

Update an existing flag.

Parameters:

• projectId (optional): Project ID
• flagId (required): Flag ID
• name, description, status, defaultValue, targetingRules, rolloutPercentage (all optional)

Example:

"Increase new-checkout rollout to 50%"
"Disable the dark-mode flag"

delete_flag

Permanently delete a flag.

Parameters:

• projectId (optional): Project ID
• flagId (required): Flag ID

toggle_flag

Toggle a flag between active and inactive.

Parameters:

• projectId (optional): Project ID
• flagId (required): Flag ID

archive_flag

Archive a flag (soft delete).

Parameters:

• projectId (optional): Project ID
• flagId (required): Flag ID

Flag Evaluation

evaluate_flag

Evaluate a flag for a specific user/context.

Parameters:

• flagKey (required): Flag key
• context (required): User context object
  • userId, email, plan, country, etc.
• environment (optional): Environment name

Example:

"Check if dark-mode is enabled for [email protected]"
"Evaluate new-checkout for a user with plan=premium"

evaluate_batch

Evaluate multiple flags at once.

Parameters:

• flagKeys (required): Array of flag keys
• context (required): User context
• environment (optional): Environment name

Natural Language AI Tools

create_flag_natural_language

Create a flag using natural language.

Parameters:

• projectId (optional): Project ID
• input (required): Natural language description
• context (optional): Additional context

Examples:

"Create a dark mode flag for premium users"
"Add a flag to roll out new checkout to 25% of users"
"Enable advanced analytics for users in US and CA"

update_flag_natural_language

Update a flag using natural language.

Parameters:

• projectId (optional): Project ID
• input (required): Natural language description
• context (optional): Should include flagKey

Examples:

"Disable the dark-mode flag"
"Increase new-checkout rollout to 75%"
"Archive the old-payment-flow flag"

Examples

Example 1: Create and Configure a Flag

User: "Create a feature flag for beta users"

AI: I'll create a beta feature flag for you.
*uses create_flag_natural_language tool*

Result: Created flag 'beta-features' with targeting rule for users with plan=beta

Example 2: Gradual Rollout

User: "Create a new-ui flag and roll it out slowly"

AI: I'll create a new UI flag with a gradual rollout.
*uses create_flag tool with rolloutPercentage: 10*

User: "Increase it to 25%"

AI: I'll increase the rollout.
*uses update_flag tool*

Result: Rollout increased to 25%

Example 3: Conditional Feature Access

User: "Create a premium-analytics flag only for enterprise users"

AI: I'll create that with enterprise targeting.
*uses create_flag_natural_language tool*

Result: Created flag with targeting rule: plan equals 'enterprise'

Example 4: Evaluate Flags

User: "Check if premium-analytics is enabled for [email protected] with plan enterprise"

AI: I'll evaluate that for you.
*uses evaluate_flag tool*

Result: {
  flagKey: "premium-analytics",
  value: true,
  reason: "Matched targeting rule: plan equals enterprise"
}

Advanced Usage

Custom API Endpoint

If you're self-hosting Flagdeck:

export FLAGDECK_API_URL=https://your-flagdeck-instance.com

Per-Request Project ID

If you manage multiple projects, omit FLAGDECK_PROJECT_ID and provide it per-request:

"List flags in project proj-123"

The AI will include projectId: "proj-123" in the tool arguments.

Environment-Specific Operations

"Evaluate dark-mode for [email protected] in staging environment"

Development

Building from Source

git clone https://github.com/flagdeck/flagdeck.git
cd packages/@flagdeck/mcp-server
npm install
npm run build

Running Locally

npm run dev

Testing

npm test

API Reference

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------|-------------| | FLAGDECK_API_KEY | Yes | - | Your Flagdeck API key | | FLAGDECK_API_URL | No | http://localhost:3008 | Flagdeck API URL | | FLAGDECK_PROJECT_ID | No | - | Default project ID | | FLAGDECK_ENVIRONMENT | No | production | Default environment |

Tool Summary

| Tool | Purpose | Required Params | |------|---------|-----------------| | list_projects | List all projects | - | | get_project | Get project details | - | | list_environments | List environments | - | | list_flags | List flags | - | | get_flag | Get flag details | flagId or flagKey | | create_flag | Create new flag | key, name, valueType, defaultValue | | update_flag | Update flag | flagId | | delete_flag | Delete flag | flagId | | toggle_flag | Toggle flag status | flagId | | archive_flag | Archive flag | flagId | | evaluate_flag | Evaluate single flag | flagKey, context | | evaluate_batch | Evaluate multiple flags | flagKeys, context | | create_flag_natural_language | AI-powered flag creation | input | | update_flag_natural_language | AI-powered flag update | input |

Troubleshooting

"FLAGDECK_API_KEY is required"

Set your API key:

export FLAGDECK_API_KEY=your-key-here

"projectId is required"

Either set FLAGDECK_PROJECT_ID or provide it in each request.

Connection Errors

Check that FLAGDECK_API_URL is correct and the API is reachable:

curl $FLAGDECK_API_URL/health

Tool Not Found

Make sure you're using a compatible MCP client (Claude Desktop, Cursor, etc.) and the server is properly configured.

Contributing

We welcome contributions! Please see our Contributing Guide.

License

MIT

Links

• Flagdeck Documentation
• MCP Specification
• GitHub Issues
• NPM Package

Built with ❤️ by the Flagdeck team