The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Unleash MCP listing page.
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.
This MCP server provides tools that integrate with the Unleash Admin API, allowing AI coding assistants to:
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 by evaluate_change to 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.See more information on the core workflow tools in the Tool reference section.
Before you can run the server, you need the following:
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.
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:
For Codex:
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.
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:
For Codex:
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 to Profile > Personal Access Tokens, and create a new token.
For Claude Code:
For Codex:
The --header flag sends the PAT directly, bypassing the OAuth flow entirely.
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:
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:
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)
B) Use TypeScript directly (no build)
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.app.log, mcp-stdio.log), both gitignored.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.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:
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.
This section describes each of the core tools in detail, including its purpose, parameters, and output.
The create_flag tool 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 running evaluate_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.description (required): Clear explanation of what the flag controls and why it exists.projectId (optional): Target project (defaults to UNLEASH_DEFAULT_PROJECT).impressionData (optional): Enable analytics tracking (defaults to false).Agent prompt
Tool payload
Tool output
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.
The evaluate_change tool 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.
Use evaluate_change at 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.
The tool returns detailed, markdown-formatted guidance for the LLM assistant based on Unleash best practices.
The guidance includes:
When evaluate_change determines a flag is needed, it provides explicit instructions to:
create_flag tool to create the feature flag.wrap_change tool to get language-specific code wrapping guidance.The evaluation process
The tool follows a clear evaluation process:
Risk assessment
The tool uses language-agnostic patterns to score risk:
Scores accumulate across matched categories. The total maps to a risk level:
The output includes a confidence score (0-1) representing the LLM's self-assessed certainty, which increases with more context provided.
An excluded category 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.
The full pattern definitions, including per-category keywords, file globs, code patterns, and reasoning, are in src/evaluation/riskPatterns.ts.
Parent flag detection
The tool looks for common patterns across languages, such as:
if (isEnabled('flag')), if client.is_enabled('flag'):const enabled = useFlag('flag')const enabled = useFlag('flag') → {enabled && <Component />}if (!isEnabled('flag')) return;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, or critical, as assessed by the user.codeContext (string): Surrounding code for parent flag detection.Agent prompt
Simple usage where you let the agent gather context:
Explicit instructions:
Tool payload
Tool output
Returns a JSON object with the evaluation result, including a needsFlag boolean, a recommendation (e.g., "create_new"), a suggested flag name, risk level, and a detailed explanation.
The detect_flag tool finds existing feature flags in the codebase so you can reuse them instead of creating duplicates. This tool is automatically integrated into the evaluate_change workflow but can also be used manually.
Use this tool before creating a new feature flag or during code evaluation to check for existing flags that might already cover your use case. This helps prevent flag duplication.
The tool returns comprehensive search instructions and uses multiple detection strategies:
The tool then follows a scoring process:
Confidence levels
The tool returns candidates with confidence scores:
≥0.7: Strong match; reuse is recommended.0.4-0.7: Possible match; review manually.<0.4: Weak match; likely create a new flag.description (required): Description of the change or feature. For example, "payment processing with Stripe", "new checkout flow".files (optional): Files being modified. For example, ["src/payments/stripe.ts", "src/checkout/flow.ts"].codeContext (optional): Nearby code to scan for flags.Agent prompt
Check for existing flags before creating a flag:
Integrated automatically in evaluation:
Tool payload
Tool output
Returns a JSON object indicating if a flag was found. If flagFound is true, it includes a candidate object with the flag's name, location, confidence score, and the reason for the match.
Match found:
No match found:
The tool wrap_change generates language-specific code snippets and guidance for wrapping code with feature flags. It helps LLMs and developers follow existing patterns in the codebase and use flags correctly.
Use this tool after you have created a feature flag (with create_flag) and need to implement it in your code. It's especially useful when you want to ensure you are following existing codebase patterns or need framework-specific examples (e.g., React, Django).
This tool is the final step in the evaluate_change → create_flag → wrap_change workflow.
The tool provides the following guidance in its response:
Supported languages and frameworks:
flagName (required): Feature flag name to wrap the code with. For example: "new-checkout-flow", or "stripe-integration".language (optional): Programming language (auto-detected from fileName if not provided). Supported: typescript, javascript, python, go, ruby, php, csharp, java, rustfileName (optional): File name being modified (helps detect language), For example: "checkout.ts", "payment.py", or "handler.go".codeContext (optional): Surrounding code to help detect existing patterns.frameworkHint (optional): Framework for specialized templates. For example, "React", "Express", "Django", "Rails", or "Spring Boot".Agent prompt
Tool payload
Tool output
Returns a comprehensive, markdown-formatted string that guides the user on how to wrap their code. This includes a quickstart, search instructions, wrapping instructions with placeholders, all available templates for the language, and links to SDK documentation.
The set_flag_rollout tool configures a flexibleRollout strategy on a feature flag environment. It sets the rollout percentage, stickiness, and optional strategy-level variants. This does not enable the flag; use toggle_flag_environment to turn it on.
Use this tool after creating a flag with create_flag to configure how traffic is distributed before enabling it. Also use it to update an existing rollout percentage or add variants.
featureName (required): Feature flag name.environment (required): Target environment (for example, "production", "development").rolloutPercentage (required): Percentage of traffic to receive the feature (0-100).projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).groupId (optional): Stickiness bucketing key (defaults to the feature name).stickiness (optional): Stickiness field (defaults to "default").title (optional): Descriptive title for the strategy.disabled (optional): Create the strategy in a disabled state (defaults to false).variants (optional): List of strategy-level variants, each with name, weight (0-1000), optional weightType ("variable" or "fix"), stickiness, and payload ({type, value}).Agent prompt
Tool payload
Tool output
Returns a confirmation with the configured percentage, a link to the flag in the Unleash Admin UI, the Admin API strategies URL, and an MCP resource link for the flag.
The get_flag_state tool fetches a feature flag's current metadata and environment strategies from the Unleash Admin API. It returns the flag's type, enabled/archived status, impression data setting, and a per-environment summary of active strategies and variants.
Use this tool to inspect a flag before modifying it, to check how many strategies are active across environments, or to find strategy IDs before calling remove_flag_strategy.
featureName (required): Feature flag name.projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).environment (optional): Filter results to a single environment (case-insensitive).Agent prompt
Tool payload
Tool output
Returns a text summary of the flag (type, enabled/archived/impression-data, project, environment summaries with strategy counts) along with UI and API links. The structured output includes the full feature object with all environments and strategy details.
The list_flags tool enumerates the feature flags in a project and returns a structured inventory with pagination and sort order. Active and archived flags are returned separately: call it once with archived: false (the default) and once with archived: true to assemble a full inventory for audit workflows.
Use this tool when an agent needs to discover which flags already exist, for example to audit a project, find candidates for cleanup, or build context before creating or wrapping a flag. It is the agent-invokable equivalent of the unleash://projects/{projectId}/feature-flags resource (see MCP resources).
projectId (optional): Project to list flags from (defaults to UNLEASH_DEFAULT_PROJECT; auto-resolved when a single project exists).archived (optional): true to list archived flags instead of active ones. Defaults to false. Active and archived flags cannot be returned in the same response.limit (optional): Maximum flags per page (default: server page size, typically 50).order (optional): Sort order by flag name, asc or desc (default: asc).offset (optional): Number of flags to skip for pagination (default: 0).Agent prompt
Tool payload
Tool output
Returns a text summary plus structured content with projectId, archived, order, limit, offset, nextOffset, totalFlags, and the flags array (each with name, type, project, archived status, and links). Use nextOffset to page through large projects.
The list_projects tool enumerates the Unleash projects available to the configured token, with pagination and sort order.
Use this tool when the target project is unknown, or when an agent needs to pick a project before listing or creating flags. It is the agent-invokable equivalent of the unleash://projects resource (see MCP resources).
limit (optional): Maximum projects per page (default: server page size, typically 20).order (optional): Sort order by project creation time, asc or desc (default: desc, newest first).offset (optional): Number of projects to skip for pagination (default: 0).Agent prompt
Tool payload
Tool output
Returns a text summary plus structured content with order, limit, offset, nextOffset, totalProjects, and the projects array (each with id, name, description, mode, creation time, and URL).
The toggle_flag_environment tool enables or disables a feature flag in a specific environment. For gradual rollouts, configure a strategy with set_flag_rollout before enabling.
Use this tool to turn a flag on after configuring a rollout strategy, or to disable a flag during an incident or after completing a rollout.
featureName (required): Feature flag name.environment (required): Environment to toggle (for example, "production").enabled (required): true to enable, false to disable.projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).Agent prompt
Tool payload
Tool output
Returns a confirmation of the new state, a summary of the environment (enabled/disabled, strategy count), and links to the flag in the Unleash Admin UI and Admin API.
The remove_flag_strategy tool deletes a strategy configuration from a feature flag environment. Use get_flag_state first to discover the strategy ID.
Use this tool to clean up stale strategies, or to replace an existing strategy by removing the old one and configuring a new one with set_flag_rollout.
featureName (required): Feature flag name.environment (required): Environment from which to remove the strategy.strategyId (required): ID of the strategy to remove (find this via get_flag_state).projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).Agent prompt
Tool payload
Tool output
Returns a confirmation of removal, a count of remaining strategies in the environment, and links to the flag in the Unleash Admin UI and Admin API.
The cleanup_flag tool generates step-by-step instructions for safely removing feature flag code from the codebase while preserving the desired code path.
Use this tool when a feature flag has completed its lifecycle:
The tool returns comprehensive cleanup instructions that guide the LLM through:
If preservePath is not provided, the tool returns instructions to ask the user which path to keep before proceeding.
flagName (required): Name of the feature flag to remove (for example, "new-checkout-flow").preservePath (optional): "enabled" to keep the flag-on code path (typical for completed rollouts), or "disabled" to keep the flag-off path (for removed experiments). If omitted, the tool prompts you to ask the user.files (optional): Specific files to clean up. If omitted, searches the entire codebase.language (optional): Programming language for specialized import cleanup guidance (for example, "typescript", "python"). Auto-detected from files if not provided.Agent prompt
Tool payload
Tool output
Returns a markdown guide covering the cleanup scope and preserved path, grep commands to find all occurrences, per-pattern removal instructions, language-specific import cleanup, and post-cleanup verification steps (re-search, run tests, manual review).
The server registers MCP resources for reading project and feature flag data. All resources return JSON and are cached for 60 seconds.
| URI template | Description |
|---|---|
unleash://projects{?limit,order,offset} | List projects. Default page size: 20, sorted by creation time (newest first). |
unleash://projects/{projectId}/feature-flags{?limit,order,offset} | List flags in a project. Default page size: 50, sorted alphabetically. |
unleash://projects/{projectId}/feature-flags/{flagName} | Single feature flag metadata. |
The first two templates accept optional query parameters: limit (page size), order (asc or desc), and offset (pagination start). Responses include fetchedAt, cached, totalProjects or totalFlags, and nextOffset fields.
Resources vs. tools: MCP resources are application-controlled, so many clients only surface them through user-driven UI (for example
#-mentions) and do not let the agent callresources/readon its own. When an agent needs to enumerate projects or flags programmatically, use thelist_projectsandlist_flagstools, which return the same data through the tool interface. Thedetect_flaginventory analysis routes through the same path.
Example resource read
Returns the first 10 feature flags in the ecommerce project, sorted alphabetically, with pagination metadata.
The server follows a focused, purpose-driven design.
{code, message, hint} format.This section provides a quick reference for all configuration options.
Environment variables:
UNLEASH_BASE_URL: Your Unleash instance URL (required). Both https://your-instance.getunleash.io and https://your-instance.getunleash.io/api are accepted — the server normalizes a trailing /api away if present, so you can paste the same value most Unleash SDKs expect.UNLEASH_PAT: Personal access token (required).UNLEASH_DEFAULT_PROJECT: The default project ID the MCP should use (optional).CLI flags:
--dry-run: Simulate operations without making actual API calls.--log-level: Set logging verbosity (debug, info, warn, error).This server encourages Unleash best practices from the official documentation:
new-checkout-flowenable-ai-recommendations not flag1.mobile-push-notifications.This server uses the Unleash Admin API. For complete API documentation, see:
GET /api/admin/projects - List projectsGET /api/admin/projects/{projectId}/features - List feature flagsPOST /api/admin/projects/{projectId}/features - Create feature flagGET /api/admin/projects/{projectId}/features/{featureName} - Get flag detailsPOST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Add rollout strategyDELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Remove strategyPOST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Enable flagPOST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Disable flagError: "UNLEASH_BASE_URL must be a valid URL": Ensure your base URL is complete, including protocol. For example, https://app.unleash-hosted.com/instance. Remove any trailing slashes.
Error: "UNLEASH_PAT is required": Check that your .env file exists and contains UNLEASH_PAT={{your-personal-access-token}}. Verify that the token is valid in Unleash.
Error: "HTTP_401": Your personal access token may be invalid or expired. Generate a new token under Profile > View Profile settings > Personal API tokens > New token.
Error: "HTTP_403": Your token doesn't have permission to create flags in this project. Review your role and permissions in Unleash.
Error: "HTTP_404": The project ID doesn't exist. Confirm the project ID in Unleash Admin UI.
Error: "HTTP_409": A flag with this name already exists in the project. Use a different name or reuse the existing flag.
MIT
This is a purpose-driven project with a focused scope. Contributions should: