npm package: @flagdeck/mcp-server
Description: Model Context Protocol server for Flagdeck - enables AI agents to manage feature flags
Author: Flagdeck
Latest version: 0.1.1

# @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

```bash
npm install -g @flagdeck/mcp-server
```

### Configuration

Set up your environment variables:

```bash
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

```bash
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`:

```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 user@example.com"
Claude: *uses evaluate_flag tool* Yes, it's enabled for that user.
```

### Cursor IDE

Add to `.cursor/mcp.json`:

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

### Windsurf

Add to Windsurf MCP configuration:

```json
{
  "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 user@example.com"
"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 user@company.com 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:

```bash
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 user@example.com in staging environment"
```

---

## Development

### Building from Source

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

### Running Locally

```bash
npm run dev
```

### Testing

```bash
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:
```bash
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:
```bash
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](../../CONTRIBUTING.md).

---

## License

MIT

---

## Links

- [Flagdeck Documentation](https://docs.flagdeck.com)
- [MCP Specification](https://modelcontextprotocol.io)
- [GitHub Issues](https://github.com/flagdeck/flagdeck/issues)
- [NPM Package](https://www.npmjs.com/package/@flagdeck/mcp-server)

---

**Built with ❤️ by the Flagdeck team**