Unleash MCP Server

A purpose-driven Model Context Protocol (MCP) server for managing Unleash feature flags. This server enables LLM-powered coding assistants to create and manage feature flags following Unleash best practices.

To share feedback, join our community Slack or open an issue on GitHub.

Overview

This MCP server provides tools that integrate with the Unleash Admin API, allowing AI coding assistants to:

• Create feature flags with proper validation and typing.
• Detect existing flags to prevent duplicates or encourage reuse.
• Evaluate changes to decide when a feature flag is needed.
• Stream progress for visibility during operations.
• Handle errors gracefully with helpful hints.
• Follow best practices from the Unleash documentation.

Available tools

The MCP server exposes the following tools:

• create_flag: Creates a feature flag in Unleash.
• evaluate_change: Scores risk and recommends feature flag usage.
• detect_flag: Discovers existing feature flags to avoid duplicates.
• wrap_change: Provides guidance on how to wrap a change in a feature flag.
• set_flag_rollout: Configures rollout strategies for a feature flag (does not enable the flag).
• get_flag_state: Surfaces a feature flag's metadata and its activation strategies.
• list_flags: Lists all feature flags in a project, with optional pagination and sort order.
• list_projects: Lists Unleash projects available to the configured token, with optional pagination.
• toggle_flag_environment: Enables or disables a feature flag in an environment.
• remove_flag_strategy: Deletes a feature flag's strategy from an environment.
• cleanup_flag: Generates instructions for safely removing flagged code paths.

Core workflow

The core workflow for an AI assistant is designed to be:

1. evaluate_change: First, assess a code change to see if a flag is needed.
2. detect_flag: This is often called automatically by evaluate_change to prevent creating duplicate flags.
3. create_flag: If a new flag is required, this tool creates it in Unleash.
4. wrap_change: Finally, this tool provides the language-specific code to implement the new flag.

See more information on the core workflow tools in the Tool reference section.

Prerequisites

Before you can run the server, you need the following:

• Node.js 22 or higher
• pnpm package manager or npm
• An Unleash instance (hosted or self-hosted)
• A personal access token with permissions to create feature flags

Get started

This section covers the different ways to install and run the Unleash MCP server. You can either follow a setup for agents (such as Claude Code and Codex), run the MCP as a standalone process using npx, or use a local development setup.

Agent setup

You can add the MCP server directly to Claude Code or Codex. Agent configurations are path-specific. You must run the following command from the root directory of the project where you want to use the MCP.

For Claude Code:

claude mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

For Codex:

codex mcp add unleash \
    --env UNLEASH_BASE_URL={{your-instance-url}} \
    --env UNLEASH_PAT={{your-personal-access-token}} \
    -- npx -y @unleash/mcp@latest --log-level error

Remote agent setup (experimental)

Instead of running the MCP server locally, you can connect directly to your Unleash instance's built-in remote MCP server over HTTP. This uses the Streamable HTTP transport — no local process needed.

Note: Remote MCP is an experimental feature that must be enabled on your Unleash instance. Contact the Unleash team to get it enabled.

OAuth

The OAuth flow opens your browser, lets you log in to Unleash, and automatically provisions a short-lived PAT. No manual token management required.

For Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

For Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport http

On first use, the client will automatically open your browser for login. After authenticating with Unleash, a PAT is created and used for all subsequent requests.

The PAT expires after 24 hours by default.

Personal Access Token (PAT)

Use this method when you already have a PAT or need headless/non-interactive access (CI pipelines, shared developer environments, clients that don't support OAuth).

To create a PAT: log in to your Unleash instance, go to Profile > Personal Access Tokens, and create a new token.

For Claude Code:

claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

For Codex:

codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer {{your-personal-access-token}}"

The --header flag sends the PAT directly, bypassing the OAuth flow entirely.

Quickstart with npx

You can run the MCP server as a standalone process without cloning the repository using npx. Provide configuration through environment variables or a local .env file in the directory where you run the command:

UNLEASH_BASE_URL={{your-instance-url}} \
UNLEASH_PAT={{your-personal-access-token}} \
UNLEASH_DEFAULT_PROJECT={{default_project_id}} \
npx @unleash/mcp@latest --log-level debug

The CLI supports the same flags as the local build (for example, --dry-run, --log-level).

Local development setup

Follow these steps to set up the project for local development.

1. Install dependencies

Clone the repository and install dependencies using pnpm. Corepack keeps everyone on the same pnpm version:

git clone https://github.com/Unleash/unleash-mcp.git
cd unleash-mcp

# Enable Corepack once per machine, then prepare the pnpm this repo expects
corepack enable
corepack prepare pnpm@11.0.8 --activate

pnpm install

2. Run in dev mode directly from Claude or Codex

Avoid npm run output and tsx watch banners because any extra stdout breaks the MCP handshake. Two quiet options:

A) Use compiled JS (most reliable)

npm run build
# or keep it hot in another terminal: npm run build:watch

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node "$(pwd)/dist/index.js"

B) Use TypeScript directly (no build)

claude mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

codex mcp add unleash-dev \
  --env UNLEASH_BASE_URL={{your-instance-url}} \
  --env UNLEASH_PAT={{your-personal-access-token}} \
  --env LOG_LEVEL=debug \
  --env APP_LOG_FILE="$(pwd)/app.log" \
  --env MCP_STDIO_LOG_FILE="$(pwd)/mcp-stdio.log" \
  -- node --no-warnings --import tsx "$(pwd)/src/index.ts"

Notes:

• node --import tsx is quiet (no npm lifecycle output) and runs TS directly; use this when you want to avoid building.
• node dist/index.js is the safest choice; pair it with npm run build:watch to rebuild on changes while the agent command stays stable.
• Logs stay in the repo root (app.log, mcp-stdio.log), both gitignored.

Logging control

• LOG_LEVEL (preferred): controls application logging verbosity (debug, info, warn, error). Defaults to error when unset.
• --log-level CLI flag: optional override for LOG_LEVEL when you want a one-off change.
• APP_LOG_FILE (optional): if set, application logs are written to this file (not stdout). If unset, logs go to stderr.
• MCP_STDIO_LOG_FILE (optional): if set, MCP stdin/stdout/stderr are tee’d into this single file with channel prefixes. Protocol messages still flow over stdout normally.

Client attribution

When an MCP client sends clientInfo during initialization (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro, and other conforming clients), the server enriches the User-Agent header on outbound Unleash Admin API calls:

User-Agent: unleash-mcp/<version> (MCP Server; client=claude-code/1.2.3)

This makes Unleash event logs answer "which AI tool created or toggled this flag" without any server-side changes. Attribution values are sanitized so they cannot break the User-Agent header.

Set UNLEASH_MCP_CLIENT_ATTRIBUTION=off to disable enrichment and revert to unleash-mcp/<version> (MCP Server). Default: enabled.

Tool reference

This section describes each of the core tools in detail, including its purpose, parameters, and output.

Create flag