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. This page covers how to install and configure the server in Claude Code, and how to install the Unleash plugin. To learn what the server can do, see Unleash MCP server.

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 24 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
UNLEASH_PAT=your-personal-access-token
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
fi

Reload your shell

source ~/.zshrc  # or ~/.bashrc

Variable	Description	Required
`UNLEASH_BASE_URL`	Your Unleash instance API URL.	Yes
`UNLEASH_PAT`	A personal access token with flag creation permissions.	Yes
`UNLEASH_MCP_SEND_FEEDBACK`	Set to `true` or `false` to opt in to or out of feedback reports without a consent prompt. With `false`, the assistant doesn’t see the `send_feedback` tool.	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}' \
  -- npx -y @unleash/mcp@latest

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

Install the Unleash plugin

The Unleash plugin for Claude Code bundles the Unleash MCP server with skills that apply FeatureOps practices. The MCP server handles the Unleash side, and the skills capture how your team works, such as which changes need a flag, how you name flags, and how you roll them out. Skills work out of the box, and you can customize them for your team.

The plugin includes the following skills:

Skill	Invoke	What it does
`featureops`	`/unleash:featureops`	Decides whether a change needs a flag, finds an existing flag before creating one, wraps code behind a flag, plans a progressive rollout, and removes stale flags.
`migrate-gitlab-flags`	`/unleash:migrate-gitlab-flags <app-dir>`	Migrates a codebase from GitLab Feature Flags to Unleash. You invoke it manually.

The featureops skill also activates on its own when your request involves feature flags, rollouts, or kill switches.

Install the plugin

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add Unleash/unleash-claude-skills
/plugin install unleash@unleash-marketplace

The plugin registers the Unleash MCP server for you, so you don’t need to follow Install the MCP server as well. Registering the server twice gives you two copies of the same tools.

Set your credentials

The plugin reads your Unleash URL and token from your shell environment:

export UNLEASH_BASE_URL=https://your-instance.getunleash.io
export UNLEASH_PAT=your-personal-access-token

Restart Claude Code or run /reload-plugins, then ask: “List my Unleash projects”.

The plugin runs the MCP server locally with npx and pins the server version its skills were tested with. To use the remote MCP server instead, see the plugin’s README.

While a skill is active, Claude Code approves the read-only Unleash tools automatically and still asks for confirmation before any change. The plugin’s server uses a different tool prefix than a server you add yourself, mcp__plugin_unleash_mcp__* instead of mcp__unleash__*, which matters if you write allow rules.

To change the defaults, such as flag naming, flag lifetimes, or which areas of your code count as high risk, add a policy override at .unleash/featureops.md in your repository, or at ~/.unleash/featureops.md for personal defaults. To learn how, see the plugin repository.

Tools and workflows

Once the server is connected, Claude Code can use every tool the Unleash MCP server exposes. To learn what the server can do and see step-by-step workflows, read Unleash MCP server. For the current list of tools, see the README on GitHub.

Feedback reports

The first time the assistant tries to send a feedback report, Claude Code shows a consent prompt in your session. The MCP server saves whether you opted in or out, so you see the prompt only once.

To opt in or out without the prompt, pass -e UNLEASH_MCP_SEND_FEEDBACK=true or -e UNLEASH_MCP_SEND_FEEDBACK=false to claude mcp add, or add the variable to the env block of your .mcp.json. To learn what a report contains, see What is recorded.

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.

To opt your whole organization in to or out of feedback reports, set UNLEASH_MCP_SEND_FEEDBACK to true or false in the env block of the Unleash server in managed-mcp.json. With false, developers don’t see a consent prompt and the assistant doesn’t see the send_feedback tool.

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 does not include /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 24+. 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.

Feedback is disabled

send_feedback returns this message if you declined the consent prompt, if Claude Code couldn’t show it, or if UNLEASH_MCP_SEND_FEEDBACK is set to false. To opt in, set UNLEASH_MCP_SEND_FEEDBACK=true in the env block of your .mcp.json, or pass it with -e to claude mcp add. To see the consent prompt again, delete feedback_consent.json from the configuration directory. Feedback settings don’t affect flag operations.