Integrate Unleash with Cursor

The Unleash MCP server connects Cursor to your Unleash instance, enabling AI-assisted feature flag management. You can evaluate code changes, create flags, generate wrapping code, manage rollouts, and clean up flags from within Cursor’s AI-first development environment.

Cursor supports MCP across two interfaces:

• Cursor IDE — The primary interface, an AI-first code editor with Agent mode, Rules, Hooks, Skills, and Plugins
• Cursor CLI — Terminal-based agent access via the agent command

Cursor’s IDE-native primitives create a layered automation system for feature flags: Rules encode your team’s conventions, Hooks validate MCP operations before they execute, Skills orchestrate multi-step workflows, and Plugins bundle everything for team distribution.

Prerequisites

Before you begin, make sure you have the following:

• Node.js 18 or later: The MCP server is distributed as an npm package
• Cursor: IDE or CLI installed
• An Unleash instance: Cloud or self-hosted, with API access enabled
• A personal access token (PAT): With permissions to create and manage feature flags

Install the MCP server

The Unleash MCP server runs as a local stdio process. Configuration differs between the IDE and CLI, but both use the same npm package and credentials.

First, create a credentials file:

$
mkdir -p ~/.unleash
$
cat > ~/.unleash/mcp.env << 'EOF'
$
UNLEASH_BASE_URL=https://your-instance.getunleash.io
$
UNLEASH_PAT=your-personal-access-token
$
UNLEASH_DEFAULT_PROJECT=default
$
EOF
$
chmod 600 ~/.unleash/mcp.env

Now configure your preferred interface:

Tool reference

The Unleash MCP server exposes the following tools.

Workflows

The Unleash MCP server supports these core workflows: evaluate and wrap code in feature flags, discover and audit flags, manage rollouts across environments, and clean up after rollout. Cursor adds another workflow unique to its architecture: Rules-guided flag evaluation.

Evaluate and wrap code in feature flags

Use this workflow when implementing a change that might affect production stability, such as a payment integration, authentication flow, or external API call.

Evaluate whether the Stripe payment integration should be behind a feature flag.
The change modifies the checkout service and handles credit card processing.

Create a release flag for the Stripe payment integration.

Wrap the Stripe checkout handler with the stripe-payment-integration flag.
This is a Node.js Express application.

1
const { isEnabled } = require('unleash-client');
2
3
app.post('/checkout', async (req, res) => {
4
  const context = { userId: req.user.id };
5
6
  if (isEnabled('stripe-payment-integration', context)) {
7
    // New Stripe payment flow
8
    const result = await stripeService.processPayment(req.body);
9
    return res.json(result);
10
  } else {
11
    // Existing payment flow
12
    const result = await legacyPaymentService.process(req.body);
13
    return res.json(result);
14
  }
15
});

Rules-guided flag evaluation

Use this workflow to automate flag evaluation based on encoded policies. When a glob-scoped Rule targets a high-risk directory, the agent evaluates risk without the developer explicitly asking.

All changes in the payments domain require feature flags. No exceptions.
Evaluate risk with evaluate_change before writing implementation code.

Manage rollouts across environments

Use this workflow to enable a flag in staging for testing while keeping it disabled in production.

What is the current state and rollout strategies for stripe-payment-integration?

Clean up after rollout

Use this workflow when a feature has been fully rolled out and the flag is no longer needed.

Clean up the stripe-payment-integration flag. The feature is fully rolled out.

The agent calls cleanup_flag and returns:

• All files and line numbers where the flag is used
• Which code path to preserve (the “enabled” branch)
• Suggestions for tests to run after removal

Review the list, remove the conditional branches, and delete the flag from Unleash.

Discover and audit flags

Use this workflow to take inventory of existing flags before creating new ones, or to run a periodic audit for cleanup candidates.

Rule templates

Cursor Rules encode your team’s FeatureOps policies, so the agent considers feature flags automatically. Store them in .cursor/rules/ as .mdc files with YAML frontmatter.

For more details on Rules, see the Cursor Rules documentation.

Always Apply: universal conventions

This Rule loads into every agent session. Use it for organization-wide flag standards.

1
---
2
description: "Feature flag conventions for all code changes"
3
alwaysApply: true
4
---
5
6
# Feature Flag Conventions
7
8
When making changes to this codebase, follow these feature flag practices:
9
10
1. **Always evaluate risk**: Before implementing high-risk changes (payments,
11
   authentication, data migrations, external integrations), use the Unleash MCP
12
   server to evaluate whether a feature flag is needed.
13
14
2. **Naming conventions**: Use the format `{domain}-{feature}-{variant}`.
15
   Examples: `checkout-stripe-integration`, `auth-sso-google`, `api-rate-limiting`.
16
17
3. **Flag types**:
18
   - `release`: For gradual feature rollouts
19
   - `experiment`: For A/B tests and experiments
20
   - `operational`: For system behavior toggles
21
   - `kill-switch`: For emergency shutdowns
22
   - `permission`: For role-based access
23
24
4. **Prefer reuse**: Before creating a new flag, check if a similar flag already
25
   exists using the detect_flag tool.
26
27
5. **Clean up after rollout**: Once a feature is fully released (100% rollout for
28
   2+ weeks), use cleanup_flag to remove dead code.
29
30
## Unleash MCP Server
31
32
This project uses the Unleash MCP server for feature flag management. Configuration
33
is in `.cursor/mcp.json`. Credentials are sourced from environment variables.
34
35
Available tools: evaluate_change, detect_flag, create_flag, wrap_change,
36
get_flag_state, set_flag_rollout, toggle_flag_environment, remove_flag_strategy,
37
cleanup_flag.

Glob-scoped: domain-specific policies

This Rule loads only when the agent works with files matching the glob pattern. Use it for high-risk domains that always require flags.

1
---
2
description: "Payment domain requires feature flags for all changes"
3
alwaysApply: false
4
globs: ["src/payments/**/*.ts", "src/payments/**/*.tsx"]
5
---
6
7
# Payments Domain — Feature Flag Policy
8
9
All changes in the payments domain require feature flags. No exceptions.
10
11
- Use `kill-switch` type for external payment provider integrations
12
  (Stripe, PayPal, etc.)
13
- Use `release` type for internal payment logic changes
14
- Naming: `payments-{feature}-{variant}`
15
  (e.g., `payments-stripe-checkout`, `payments-refund-v2`)
16
- Always include a fallback path for external provider calls
17
- Evaluate risk with evaluate_change before writing implementation code

Apply Intelligently: rollout guidance

This Rule loads automatically when the agent detects the conversation is about rollout strategies.

1
---
2
description: "Guidance for configuring feature flag rollout strategies. Use when
3
  setting up rollouts, configuring milestones, or discussing gradual releases."
4
alwaysApply: false
5
---
6
7
# Rollout Strategy Defaults
8
9
When setting up rollouts with set_flag_rollout, use these defaults unless
10
specified otherwise:
11
12
- Start at 10% rollout
13
- Wait 24 hours before advancing
14
- Pause if error rate exceeds 1% or p95 latency increases by more than 20%
15
16
## Standard milestones
17
18
| Milestone | Percentage | Hold period | Advance condition |
19
|-----------|-----------|-------------|-------------------|
20
| Canary | 10% | 24 hours | Error rate < 1%, latency stable |
21
| Beta | 50% | 48 hours | Error rate < 0.5%, no regressions |
22
| GA | 100% | — | All metrics healthy for 48 hours |
23
24
## Cleanup cadence
25
26
Run cleanup_flag weekly for flags that have been at 100% for more than 14 days.

Hook examples

Hooks automate validation and auditing of MCP operations. Store them in .cursor/hooks.json at your project root.

For more details on hooks, see the Cursor Hooks documentation.

Validate flag naming before creation

This hook fires before any Unleash MCP tool call. If the tool is create_flag, it checks the flag name against your naming convention and blocks requests that violate it.

1
{
2
  "version": 1,
3
  "hooks": {
4
    "beforeMCPExecution": [
5
      {
6
        "command": ".cursor/hooks/validate-flag-name.sh",
7
        "matcher": "MCP:unleash",
8
        "timeout": 10,
9
        "failClosed": true
10
      }
11
    ]
12
  }
13
}

$
#!/bin/bash
$
input=$(cat)
$
tool_name=$(echo "$input" | jq -r '.tool_name // empty')
$
$
if [[ "$tool_name" == "create_flag" ]]; then
$
  flag_name=$(echo "$input" | jq -r '.tool_input' | jq -r '.name // empty')
$
  # Check naming convention: {domain}-{feature}-{variant}
$
  if [[ ! "$flag_name" =~ ^[a-z]+-[a-z]+-[a-z]+$ ]]; then
$
    cat << EOF
$
{
>
  "permission": "deny",
>
  "agent_message": "Flag name '$flag_name' does not follow the naming convention {domain}-{feature}-{variant}. Please use lowercase with hyphens."
>
}
$
EOF
$
    exit 0
$
  fi
$
fi
$
$
echo '{"permission": "allow"}'

Audit all MCP operations

This hook fires after every Unleash MCP tool call and logs the operation for audit purposes.

1
{
2
  "version": 1,
3
  "hooks": {
4
    "afterMCPExecution": [
5
      {
6
        "command": ".cursor/hooks/audit-mcp.sh",
7
        "matcher": "MCP:unleash"
8
      }
9
    ]
10
  }
11
}

$
#!/bin/bash
$
input=$(cat)
$
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
$
mkdir -p .cursor/hooks/logs
$
echo "[$timestamp] $(echo "$input" | jq -c '{tool: .tool_name, duration: .duration}')" >> .cursor/hooks/logs/mcp-audit.log
$
exit 0

Unleash plugin

A plugin bundles MCP tools, Rules, Skills, and Hooks into a single installable package. The Unleash plugin is the recommended way to distribute the integration across teams and projects.

Directory structure

unleash-featureops/
├── .cursor-plugin/
│   └── plugin.json
├── rules/
│   ├── feature-flag-conventions.mdc
│   ├── payments-flags.mdc
│   └── rollout-guidance.mdc
├── skills/
│   └── evaluate-and-flag/
│       └── SKILL.md
├── hooks.json
└── mcp.json

plugin.json

1
{
2
  "name": "unleash-featureops",
3
  "description": "Automate feature flag management with Unleash. Evaluate code changes for risk, create flags with consistent naming, generate SDK wrapping code, manage rollouts, and clean up stale flags.",
4
  "version": "1.0.0",
5
  "author": {
6
    "name": "Unleash"
7
  }
8
}

SKILL.md

Skills are invoked with /skill-name in chat or discovered automatically by the agent when the context is relevant.

1
# Evaluate and Flag
2
3
Evaluate whether current changes need a feature flag, then create and wrap it.
4
5
## Steps
6
7
1. Use `evaluate_change` to assess the risk of the current changes
8
2. If a flag is needed, use `detect_flag` to check for existing similar flags
9
3. If no suitable flag exists, use `create_flag` with the recommended name and type
10
4. Use `wrap_change` to generate framework-specific guard code
11
5. Suggest a rollout strategy based on the change's risk level

mcp.json

1
{
2
  "mcpServers": {
3
    "unleash": {
4
      "command": "npx",
5
      "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
6
      "envFile": "~/.unleash/mcp.env"
7
    }
8
  }
9
}

Install the plugin

• From Team Marketplace: Admin imports the GitHub repository via Dashboard > Settings > Plugins. Set as required for automatic installation across the team.
• Local testing: Symlink to ~/.cursor/plugins/local/unleash-featureops:

$
ln -s /path/to/unleash-featureops ~/.cursor/plugins/local/unleash-featureops

For more details on creating and distributing plugins, see the Cursor Plugins documentation.

Prompt patterns

The following prompt patterns help you use the MCP tools effectively.

Evaluate whether the [description of change] should be behind a feature flag.
The change modifies [component/service].

Before creating a new flag for [feature], check if a similar flag already exists
and suggest reusing it if appropriate.

Enable [flagName] in the staging environment.

What is the current state and rollout strategies for [flagName]?

Clean up the [flagName] flag now that the feature has fully shipped.

Clean up the [flagName] flag after the A/B testing experiment, only keep [variant].

/evaluate-and-flag

$
# Interactive
$
agent "Evaluate whether the Stripe integration should be behind a feature flag"
$
$
# Non-interactive
$
agent -p "Check if any changes in this branch should be feature flagged" --output-format text
$
$
# Cloud handoff
$
agent -c "Add feature flags to all payment endpoints and open a PR"

Enterprise governance

Cursor provides enterprise controls relevant to MCP server deployment.

• MCP server trust management — Enterprise admins can whitelist or blocklist specific MCP servers at the organization level. Ensure the Unleash MCP server is on the whitelist.
• Privacy mode — Enforces zero data retention with AI providers. Enabled by default for team members. Does not affect MCP server communication, which goes directly to your Unleash instance.
• Team Rules — Organization-wide Rules with enforcement toggles. Prevent developers from disabling mandatory FeatureOps policies.
• Team hooks — Enterprise-distributed hooks that sync to team members every 30 minutes via the web dashboard. Use these for MCP validation and audit logging.
• Agent sandbox — Enforceable org-wide on Enterprise plans. Controls what the agent can execute autonomously.
• Audit logs — Track administrative actions including MCP-related operations.
• SSO/SCIM — SAML/OIDC authentication and automated user provisioning.

For MCP server governance, commit .cursor/mcp.json and .cursor/hooks.json to version control. This ensures all team members use the same MCP servers with the same validation rules.

Troubleshooting

Best practices

Follow these guidelines for effective feature flag management with Cursor.

Related resources

• Unleash MCP server on GitHub
• Unleash MCP on cursor.directory (one-click install)
• Cursor and Unleash: Feature Flags Built into Your AI-First IDE
• Cursor documentation
• Cursor MCP configuration
• Impact Metrics
• Unleash architecture overview