Unleash

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.

The core workflow for an AI assistant is designed to be:
- evaluate_change: First, assess a code change to see if a flag is needed.
- detect_flag: This is often called automatically byevaluate_changeto prevent creating duplicate flags.
- create_flag: If a new flag is required, this tool creates it in Unleash.
- wrap_change: Finally, this tool provides the language-specific code to implement the new flag.

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

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.

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

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

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

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

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

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.

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 toProfile>Personal Access Tokens, and create a new token.

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

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

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

You can run the MCP server as a standalone process without cloning the repository usingnpx. Provide configuration through environment variables or a local.envfile 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 --log-level debug

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

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

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

- Run in dev mode directly from Claude or Codex

Avoidnpm runoutput andtsx watchbanners because any extra stdout breaks the MCP handshake. Two quiet options:

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"

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"

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

- LOG_LEVEL(preferred): controls application logging verbosity (debug,info,warn,error). Defaults toerrorwhen unset.
- --log-levelCLI flag: optional override forLOG_LEVELwhen 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.

When an MCP client sendsclientInfoduring initialization (Claude Code, Cursor, Copilot, Windsurf, Codex, Kiro, and other conforming clients), the server enriches theUser-Agentheader 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.

SetUNLEASH_MCP_CLIENT_ATTRIBUTION=offto disable enrichment and revert tounleash-mcp/<version> (MCP Server). Default: enabled.

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

Thecreate_flagtool creates a new feature flag in Unleash with comprehensive validation and progress tracking.

Use this tool when you have already determined that a feature flag is required (for example, after runningevaluate_change) and you are ready to create it with the correct type and metadata.

The tool accepts the following parameters:

- name(required): Unique feature flag name within the project.
- type(required): Feature flag type indicating lifecycle and intent.

- release: Gradual feature rollouts to users.
- experiment: A/B tests and experiments.
- operational: System behavior and operational toggles.
- kill-switch: Emergency shutdowns or circuit breakers.
- permission: Control feature access based on user roles or entitlements.

Use create_flag with: - name: "new-checkout-flow" - type: "release" - description: "Gradual rollout of the redesigned checkout experience" - projectId: "ecommerce"

{ "name": "new-checkout-flow", "type": "release", "description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking", "projectId": "ecommerce", "impressionData": true }

On success, the tool returns a JSON object containing the new feature flag's URL in the Unleash Admin UI, an MCP resource link for programmatic access, creation timestamp, and configuration details.

Theevaluate_changetool evaluates whether a code change should be behind a feature flag. It examines the structure, context, and potential risk of the change and returns a recommendation with an explanation and next steps.

Useevaluate_changeat the beginning of a feature or modification when you want to understand whether the work requires a feature flag. This tool is also helpful when you are unsure which flag type to use or want guidance on rollout planning.

- Parent flag detection: Checks if code is already protected by existing flags.
- Risk assessment: Analyzes code patterns to identify risky operations.
- Code type evaluation: Classifies the change (for example, test, config, feature, or bug fix).
- Recommendation: Suggests whether to create a flag, use an existing flag, or skip the flag.
- Next actions: Provides specific instructions on what to do next.

Whenevaluate_changedetermines a flag is needed, it provides explicit instructions to:
- Callcreate_flagtool to create the feature flag.
- Callwrap_changetool to get language-specific code wrapping guidance.
- Implement the wrapped code following the detected patterns.

The tool follows a clear evaluation process:

Step 1: Gather code changes (git diff, read files) ↓ Step 2: Check for parent flags (avoiding nesting) ↓ Step 3: Assess code type (test? config? feature?) ↓ Step 4: Evaluate risk (auth? payments? API changes?) ↓ Step 5: Calculate risk score ↓ Step 6: Make recommendation ↓ Step 7: Take action (create flag or proceed without)

The tool uses language-agnostic patterns to score risk:

- Critical risk(Score +5): For example, auth, payments, security, and database operations.
- High risk(Score +3): For example, API changes, external services, or new classes.
- Medium risk(Score +2): For example, async operations or state management.
- Low risk(Score +1): For example, bug fixes, refactors, or small changes.

Scores accumulate across matched categories. The total maps to a risk level:

- Critical: Score ≥ 5
- High: Score ≥ 3
- Medium: Score ≥ 2
- Low: Score < 2

The output includes aconfidencescore (0-1) representing the LLM's self-assessed certainty, which increases with more context provided.

Anexcludedcategory covers files that do not need feature flags regardless of content: test files (.test.ts,_test.go, etc.), configuration files (.config.js,.env,.yaml), and documentation files (.md,docs/). Changes limited to excluded files will not trigger a flag recommendation.

- Conditionals:if (isEnabled('flag')),if client.is_enabled('flag'):
- Assignments:const enabled = useFlag('flag')
- Hooks:const enabled = useFlag('flag')→{enabled && <Component />}
- Guards:if (!isEnabled('flag')) return;
- Wrappers*:withFeatureFlag('flag', () => {...})

All parameters are optional, but more context leads to better recommendations:

- repository(string): Repository name or path.
- branch(string): Current branch name.
- files(array): List of files being changed.
- description(string): Description of the change.
- riskLevel(enum):low,medium,high, orcritical, as assessed by the user.
- codeContext(string): Surrounding code for parent flag detection.

Simple usage where you let the agent gather context:

Use evaluate_change to help me determine if I need a feature flag

Use evaluate_change with: - description: "Add Stripe payment processing" - riskLevel: "high"