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.

Experimental feature

The Unleash MCP server is an experimental feature. Functionality may change, and we do not yet recommend using it in production environments.

To share feedback, join our community Slack, open an issue on GitHub, or email us at beta@getunleash.io.

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.
• 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 18 or higher
• Yarn 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

... View full README on GitHub