Integrate Unleash with Claude Code

The Unleash MCP server connects Claude Code 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 your terminal or IDE.

Claude Code supports MCP across multiple interfaces:

• Terminal CLI — The primary interface, built for developers who live in the terminal.
• VS Code — Extension for Visual Studio Code.
• JetBrains IDEs — Plugin for IntelliJ IDEA, PyCharm, WebStorm, and others.
• Desktop app — Standalone application.
• GitHub Actions — CI/CD automation with @anthropics/claude-code-action.

Prerequisites

Before you begin, make sure you have the following:

• Node.js 18 or later: the MCP server is distributed as an npm package.
• Claude Code, installed via your preferred method (see installation tabs).
• 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 by interface, but all use the same npm package and credentials.

Claude Code uses environment variable expansion, and we recommend creating a credentials file and source it from your shell profile:

$
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

$
if [ -f ~/.unleash/mcp.env ]; then
$
  source ~/.unleash/mcp.env
$
  export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
$
fi

$
source ~/.zshrc  # or ~/.bashrc

Configure your interface

$
claude mcp add --transport stdio --scope project unleash \
>
  -e UNLEASH_BASE_URL='${UNLEASH_BASE_URL}' \
>
     UNLEASH_PAT='${UNLEASH_PAT}' \
>
     UNLEASH_DEFAULT_PROJECT='${UNLEASH_DEFAULT_PROJECT:-default}' \
>
  -- npx -y @unleash/mcp@latest --log-level error

$
claude mcp get unleash

Name: unleash
Type: stdio
Command: npx -y @unleash/mcp@latest --log-level error
Scope: Project config (shared via .mcp.json)

Tool reference

The Unleash MCP server exposes the following tools.

Workflows

The Unleash MCP server supports three use cases: evaluate and wrap code in feature flags, manage rollouts across environments, and clean up after rollout.

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
});

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.

Claude Code 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.

CLAUDE.md templates

Claude Code reads a CLAUDE.md file at the project root and applies its guidance automatically. You can encode your team’s feature flag policies in this file so Claude Code considers them on every interaction.

Basic template

1
# Project Instructions
2
3
## Feature Flag Guidelines
4
5
When making changes to this codebase:
6
7
1. **Always evaluate risk** — Before implementing changes to payments, authentication, 
8
   data migrations, or external integrations, use the Unleash MCP server to evaluate 
9
   whether a feature flag is needed.
10
11
2. **Naming conventions** — Use the format `{domain}-{feature}-{variant}`. 
12
   Examples: `checkout-stripe-integration`, `auth-sso-google`, `api-rate-limiting`.
13
14
3. **Flag types**:
15
   - `release` — For gradual feature rollouts
16
   - `experiment` — For A/B tests
17
   - `operational` — For system behavior toggles
18
   - `kill-switch` — For emergency shutdowns
19
20
4. **Check before creating** — Always check for existing flags before creating new ones.
21
22
5. **Clean up after rollout** — Once a feature is at 100% for 2+ weeks, use cleanup_flag.
23
24
## Unleash MCP Server
25
26
This project uses the Unleash MCP server. Configuration is in `.mcp.json`.

Advanced template with domain rules

1
# Project Instructions
2
3
## Feature Flag Guidelines
4
5
### Domain-specific rules
6
7
- **Payments domain** (`src/payments/`): Always require flags for any changes.
8
- **Authentication domain** (`src/auth/`): Require flags for SSO, MFA, and session changes.
9
- **UI components** (`src/components/`): Flags optional for styling, required for behavior.
10
- **API endpoints** (`src/api/`): Require flags for breaking changes.
11
12
### Rollout defaults
13
14
When using set_flag_rollout, apply these defaults:
15
- Start at 10%
16
- Wait 24 hours before advancing
17
- Pause if error rate exceeds 1%
18
19
### Cleanup cadence
20
21
Run cleanup_flag weekly for flags at 100% for more than 14 days.

Commit your CLAUDE.md file to version control so all team members share the same policies.

Piped workflow recipes

Claude Code’s pipe-friendly interface enables batch operations. Combine standard Unix tools with Claude Code to process data that the MCP server cannot access directly.

Find commits that should have been flagged

$
git log --oneline -20 | claude -p "Review these commits. For each, use evaluate_change to determine if it should have been feature flagged. Report gaps."

Analyze a diff before merging

$
git diff main...feature-branch | claude -p "Analyze this diff. Use evaluate_change to determine which changes need feature flags."

Pre-commit hook for flag evaluation

$
#!/bin/bash
$
git diff --cached | claude -p "Evaluate this staged diff for feature flag requirements" --output-format json

Find flag references and check their state

$
grep -r "isEnabled\|is_enabled" src/ | claude -p "Extract flag names from these references. Use get_flag_state to check if each exists in Unleash and report mismatches."

Direct Unleash queries

For operations that only need Unleash data, ask Claude Code directly:

$
claude -p "List all feature flags and identify any that haven't been modified in 90 days"
$
claude -p "Check all flags against our naming convention and report violations"
$
claude -p "Generate a cleanup report for flags at 100% rollout for more than 2 weeks"

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].

Enterprise governance

For enterprise deployments, IT administrators can deploy centralized MCP configuration using managed settings.

Managed MCP configuration

Deploy managed-mcp.json to system directories to control which MCP servers are available:

When this file is present, users cannot add, modify, or use any MCP servers other than those defined in the file.

Policy-based control

Use allowedMcpServers and deniedMcpServers in managed settings to restrict which servers users can configure while still allowing some flexibility.

Troubleshooting

$
claude mcp add --transport stdio my-server -- cmd /c npx -y @unleash/mcp@latest

Best practices

Follow these guidelines for effective feature flag management with Claude Code.

Related resources

• Unleash MCP server on GitHub
• Claude Code and Unleash: When Agentic AI Gets Release Governance
• Impact Metrics
• Unleash architecture overview
• Claude Code documentation