Integrate Unleash with Claude Code for AI-powered feature flag management

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:

Create credentials file

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

Source in shell profile

Add to your ~/.zshrc or ~/.bashrc:

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

Reload your shell

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

Variable	Description	Required
`UNLEASH_BASE_URL`	Your Unleash instance API URL. Include `/api` at the end.	Yes
`UNLEASH_PAT`	A personal access token with flag creation permissions.	Yes
`UNLEASH_DEFAULT_PROJECT`	The default project for flag operations. If omitted, you must specify `projectId` in each tool call.	No

Configure your interface

Terminal CLI

VS Code

JetBrains IDEs

Desktop App

GitHub Actions

Requirements: Claude Code CLI installed.

The terminal CLI is Claude Code’s native interface. Use the claude mcp add command to register the Unleash MCP server.

Install Claude Code

Choose your preferred installation method.

Add the Unleash MCP server

You can either run the claude mcp add command or create the .mcp.json file manually.

Both approaches create the same .mcp.json file at your project root. Choose whichever you prefer.

CLI command

Create file manually

Run the following command from your project directory:

$ 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

Syntax notes:

The server name (unleash) comes before the -e flag
Multiple environment variables are space-separated after a single -e
Single quotes around ${VAR} preserve the literal string for runtime expansion

The resulting .mcp.json file can be committed to version control since it contains no credentials, only variable references that expand at runtime.

Verify the installation

$ claude mcp get unleash

You should see output confirming the server configuration:

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

Within a Claude Code session, you can also run /mcp to see connected servers and available tools.

Installation scopes:

Scope	Storage	Use case
Local (default)	`~/.claude.json`	Personal, single-project configs
Project	`.mcp.json` in project root	Team-shared, version controlled
User	`~/.claude.json`	Available across all projects

For team collaboration, use --scope project so the configuration is stored in .mcp.json and can be committed to version control.

Tool reference

The Unleash MCP server exposes nine tools. The following table summarizes each tool and when to use it.

Tool	Description	When to use
`evaluate_change`	Analyzes a code change and determines whether it should be behind a feature flag.	Before implementing risky changes
`detect_flag`	Searches for existing flags that match a description to prevent duplicates.	Before creating new flags
`create_flag`	Creates a new feature flag with proper naming, typing, and metadata.	When no suitable flag exists
`wrap_change`	Generates framework-specific code to guard a feature behind a flag.	After creating a flag
`get_flag_state`	Returns the current state, strategies, and metadata for a flag.	Debugging, status checks
`set_flag_rollout`	Configures rollout percentages and activation strategies.	Gradual releases
`toggle_flag_environment`	Enables or disables a flag in a specific environment.	Testing, staged rollouts
`remove_flag_strategy`	Deletes a rollout strategy from a flag.	Simplifying flag configuration
`cleanup_flag`	Returns file locations and instructions for removing a flag after rollout.	After full rollout

Workflows

This section describes common workflows for using the Unleash MCP server with Claude Code.

Evaluate and wrap a risky change

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

Evaluate the change

Tell Claude Code what you are working on:

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

Claude Code calls evaluate_change and returns a recommendation with a suggested flag name.

Check for duplicates

Claude Code automatically calls detect_flag to search for existing flags. If a suitable flag exists, Claude Code suggests reusing it instead of creating a duplicate.

Create the flag

If no suitable flag exists:

Create a release flag for the Stripe payment integration.

Claude Code calls create_flag with the appropriate name, type, and description. The flag is created in Unleash, disabled by default.

Wrap the code

Generate framework-specific guard code:

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

Claude Code calls wrap_change and returns code like this:

checkout.js

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.

Check flag state

Enable in staging

Configure rollout

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

Claude Code calls get_flag_state and returns the flag metadata, enabled environments, and active strategies.

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.

Feature flags should be temporary. Regularly clean up flags after successful rollouts to prevent technical debt.

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

CLAUDE.md

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

CLAUDE.md

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

.git/hooks/pre-commit

$ #!/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 and create a flag

Intent: Determine if a change requires a feature flag, then create and wrap it.

Prompt:

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

Expected behavior: Claude Code calls evaluate_change, then detect_flag, create_flag, and wrap_change as needed.

Detect and reuse existing flags

Intent: Avoid duplicate flags when similar functionality exists.

Prompt:

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

Expected behavior: Claude Code calls detect_flag and presents matches with confidence levels.

Toggle or check flag state

Intent: Enable, disable, or query a flag in a specific environment.

Prompts:

Enable [flagName] in the staging environment.

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

Expected behavior: Claude Code calls toggle_flag_environment or get_flag_state.

Clean up a flag

Intent: Safely remove flagged code and delete unused flags.

Prompts:

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

Expected behavior: Claude Code calls cleanup_flag and provides removal instructions.

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:

Platform	Path
macOS	`/Library/Application Support/ClaudeCode/managed-mcp.json`
Linux/WSL	`/etc/claude-code/managed-mcp.json`
Windows	`C:\Program Files\ClaudeCode\managed-mcp.json`

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

MCP tools not showing up

Verify the server is listed with claude mcp list
Check that environment variables are exported: echo $UNLEASH_BASE_URL
Test credentials directly: curl -H "Authorization: $UNLEASH_PAT" "$UNLEASH_BASE_URL/api/admin/projects"
Restart your terminal after modifying your shell profile

Environment variables not expanding

Restart your terminal after modifying ~/.zshrc or ~/.bashrc
Verify variables are exported: export UNLEASH_BASE_URL UNLEASH_PAT
Check that single quotes were used in the claude mcp add command to prevent premature expansion

Authentication failed

Confirm your Unleash PAT is valid and has not expired
Check that the PAT has permissions to create and manage feature flags
Verify that UNLEASH_BASE_URL includes /api at the end
For self-hosted instances, ensure the API is accessible from your machine

Server crashes repeatedly

Claude Code automatically restarts MCP servers that crash. If a server fails repeatedly, it will be disabled for the session. Check your credentials and restart Claude Code.

Node.js not found

Local servers using npx require Node.js 18+. Verify with node --version. If Node.js is installed but not found, check your PATH.

Windows-specific issues

On native Windows (not WSL), local MCP servers using npx require the cmd /c wrapper:

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

For WSL environments, use the standard Unix syntax.

Tool results truncated

Claude Code limits tool output size to prevent context overflow. If results appear truncated, use filters (such as specific projects or flag types) to reduce result size. For current limits, see the Claude Code MCP documentation.

Best practices

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

Keep humans in the loop

While the MCP server can automate flag creation, high-risk changes should involve human review. Approve flag creation, rollout plans, and cleanup decisions.

Define naming conventions

Establish organization-wide standards for flag names (e.g., domain-feature-variant) and types. Encode these in your CLAUDE.md file.

Prevent duplication

Always use detect_flag before creating new flags. This keeps naming consistent and reduces fragmentation across services.

Keep flags temporary

Feature flags should be removed after successful rollouts. Use cleanup_flag regularly to prevent technical debt.

Use project scope for teams

Configure MCP servers with --scope project so the .mcp.json file is shared via version control. All team members get the same configuration.

Encode policies in CLAUDE.md

Write your feature flag guidelines in CLAUDE.md. Claude Code reads this file and applies its guidance automatically.