The Unleash MCP Server enables AI coding assistants to manage Unleash feature flags through the full lifecycle — from creation to cleanup — by integrating with the Unleash Admin API.
Evaluate code changes: Assess whether a code change requires a feature flag by analyzing risk level, code type, and context, returning a scored recommendation with next steps.
Detect existing flags: Search the codebase for existing feature flags using file-based detection, git history analysis, and semantic matching to prevent duplicates and encourage reuse.
Create feature flags: Create new flags with proper validation, choosing from types: release, experiment, operational, kill-switch, or permission.
Wrap code with flags: Generate language- and framework-specific code snippets (TypeScript, JavaScript, Python, Go, Ruby, PHP, C#, Java, Rust — with React, Django, Rails, Spring Boot, etc.) for implementing feature flags.
Configure rollout strategies: Set up flexibleRollout strategies with percentage, stickiness, variants, and group ID for a flag in a specific environment.
Toggle flag environments: Enable or disable a feature flag in a specific environment (e.g., production, development).
Inspect flag state: Fetch a flag's current metadata, enabled/archived status, and per-environment strategy details including strategy IDs.
Remove flag strategies: Delete a specific strategy configuration from a flag environment to clean up or replace rollout rules.
Clean up flag code: Generate step-by-step instructions for safely removing feature flag code from the codebase while preserving the correct code path.
List feature flags: Enumerate active or archived flags in a project with pagination and sort order for auditing and discovery.
List projects: Discover available Unleash projects accessible to the configured token.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Unleash MCP Server create a new feature flag for the dark mode rollout"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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.
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.
Related MCP server: OpenFeature MCP Server
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
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:
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 errorFor 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 errorInstead 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:
claude mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport httpFor Codex:
codex mcp add unleash https://{{your-instance-url}}/api/admin/mcp --transport httpOn 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:
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.
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 --log-level debugThe 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.
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 installRun 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.
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:
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.
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
Use create_flag with:
- name: "new-checkout-flow"
- type: "release"
- description: "Gradual rollout of the redesigned checkout experience"
- projectId: "ecommerce"Tool payload
{
"name": "new-checkout-flow",
"type": "release",
"description": "Gradual rollout of the redesigned checkout experience with improved conversion tracking",
"projectId": "ecommerce",
"impressionData": true
}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:
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.
When evaluate_change determines a flag is needed, it provides explicit instructions to:
Call create_flag tool to create the feature flag.
Call wrap_change tool to get language-specific code wrapping guidance.
Implement the wrapped code following the detected patterns.
The evaluation process
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)Risk assessment
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 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:
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, 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:
Use evaluate_change to help me determine if I need a feature flagExplicit instructions:
Use evaluate_change with:
- description: "Add Stripe payment processing"
- riskLevel: "high"Tool payload
{
"repository": "my-app",
"branch": "feature/stripe-integration",
"files": ["src/payments/stripe.ts"],
"description": "Add Stripe payment processing",
"riskLevel": "high",
"codeContext": "surrounding code for parent flag detection"
}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.
{
"needsFlag": true,
"reason": "new_feature",
"recommendation": "create_new",
"suggestedFlag": "stripe-payment-integration",
"riskLevel": "critical",
"riskScore": 5,
"explanation": "This change integrates Stripe payments, which is critical risk...",
"confidence": 0.9
}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:
File-based detection: Search in files you're modifying for existing flags.
Git history analysis: Look for recently added flags in commit history.
Semantic name matching: Match descriptions to existing flag names.
Code context analysis: Inspect code around the change.
The tool then follows a scoring process:
Step 1: Execute file-based search (grep for flag patterns in target files)
↓
Step 2: Search git history for recent flag additions
↓
Step 3: Perform semantic matching (description → flag names)
↓
Step 4: Analyze code context (if provided)
↓
Step 5: Combine scores from all methods
↓
Step 6: Return best candidate with confidence scoreConfidence levels
The tool returns candidates with confidence scores:
High ≥0.7: Strong match; reuse is recommended.
Medium 0.4-0.7: Possible match; review manually.
Low <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:
Use detect_flag with description "payment processing with Stripe"Integrated automatically in evaluation:
Use evaluate_change - automatically searches for existing flagsTool payload
{
"description": "payment processing with Stripe",
"files": ["src/payments/stripe.ts"]
}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:
{
"flagFound": true,
"candidate": {
"name": "stripe-payment-integration",
"location": "src/payments/stripe.ts:42",
"context": "if (client.isEnabled('stripe-payment-integration')) {",
"confidence": 0.85,
"reasoning": "Found in same file you're modifying, added 2 days ago",
"detectionMethod": "file-based"
}
}No match found:
{
"flagFound": false,
"candidate": null
}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:
Search instructions: Step-by-step guide for finding existing flag patterns in your codebase using grep.
Pattern detection: Identifies common patterns (for example, imports, client variable names, method names, or wrapping styles).
Default templates: Fallback code snippets if no patterns are found.
Framework-specific examples: Specialized patterns for React, Express, Django, and others.
Multiple patterns: If-blocks, guard clauses, hooks, decorators, middleware, and more.
Supported languages and frameworks:
TypeScript/JavaScript: Node.js, React Hooks, Express middleware.
Python: FastAPI, Django, Flask decorators.
Go: Standard if-blocks, HTTP middleware.
Ruby: Rails controllers.
PHP: Laravel controllers.
C#: .NET/ASP.NET controllers.
Java: Spring Boot.
Rust: Actix/Rocket handlers.
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, rust
fileName (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
Use wrap_change with:
- flagName: "new-checkout-flow"
- fileName: "src/components/checkout.ts"
- frameworkHint: "React"Tool payload
{
"flagName": "new-checkout-flow",
"fileName": "checkout.ts",
"frameworkHint": "React"
}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.
# Feature Flag Wrapping Guide: "new-checkout-flow"
**Language:** TypeScript
**Framework:** React
## Quick Start
[Recommended pattern with import and usage]
## How to Search for Existing Flag Patterns
[Step-by-step Grep instructions]
## How to Wrap Code with Feature Flag
[Wrapping instructions with examples]
## All Available Templates
[If-block, guard clause, hooks, ternary, etc.]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
Use set_flag_rollout with:
- featureName: "new-checkout-flow"
- environment: "production"
- rolloutPercentage: 25Tool payload
{
"featureName": "new-checkout-flow",
"environment": "production",
"rolloutPercentage": 25,
"projectId": "ecommerce",
"stickiness": "userId"
}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
Use get_flag_state with:
- featureName: "new-checkout-flow"
- environment: "production"Tool payload
{
"featureName": "new-checkout-flow",
"projectId": "ecommerce",
"environment": "production"
}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
Use list_flags with:
- projectId: "ecommerce"
- archived: falseTool payload
{
"projectId": "ecommerce",
"archived": false,
"limit": 50,
"order": "asc"
}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
Use list_projects to see which projects are available.Tool payload
{
"limit": 20,
"order": "desc"
}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
Use toggle_flag_environment with:
- featureName: "new-checkout-flow"
- environment: "production"
- enabled: trueTool payload
{
"featureName": "new-checkout-flow",
"environment": "production",
"enabled": true,
"projectId": "ecommerce"
}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
Use get_flag_state to find strategy IDs for "new-checkout-flow" in production,
then use remove_flag_strategy to delete the old strategy.Tool payload
{
"featureName": "new-checkout-flow",
"environment": "production",
"strategyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"projectId": "ecommerce"
}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:
After a rollout reaches 100% and the flag is no longer needed.
When deprecating an experimental feature (preserve the disabled path).
When removing a kill switch that is no longer necessary.
During technical debt cleanup of old flags.
The tool returns comprehensive cleanup instructions that guide the LLM through:
Finding all occurrences of the flag using grep patterns.
Identifying usage patterns (if-else blocks, ternary expressions, guard clauses, hooks, decorators, middleware).
Removing flag checks while preserving the correct code path.
Cleaning up unused imports with language-specific guidance.
Verifying changes with post-cleanup search and test steps.
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
Use cleanup_flag with:
- flagName: "new-checkout-flow"
- preservePath: "enabled"Tool payload
{
"flagName": "new-checkout-flow",
"preservePath": "enabled",
"files": ["src/components/checkout.tsx", "src/api/checkout.ts"],
"language": "typescript"
}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 |
| List projects. Default page size: 20, sorted by creation time (newest first). |
| List flags in a project. Default page size: 50, sorted alphabetically. |
| 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
Read unleash://projects/ecommerce/feature-flags?limit=10&order=ascReturns the first 10 feature flags in the ecommerce project, sorted alphabetically, with pagination metadata.
The server follows a focused, purpose-driven design.
src/
├── index.ts # Stdio CLI entry point
├── server.ts # Transport-agnostic server factory
├── remote.ts # HTTP request handler for embedded mode
├── config.ts # Configuration loading and validation
├── context.ts # Shared runtime context
├── version.ts # Version constant
├── unleash/
│ └── client.ts # Unleash Admin API client
├── tools/
│ ├── types.ts # Shared ToolDefinition type
│ ├── createFlag.ts # create_flag tool
│ ├── evaluateChange.ts # evaluate_change tool
│ ├── detectFlag.ts # detect_flag tool
│ ├── wrapChange.ts # wrap_change tool
│ ├── cleanupFlag.ts # cleanup_flag tool
│ ├── setFlagRollout.ts # set_flag_rollout tool
│ ├── getFlagState.ts # get_flag_state tool
│ ├── toggleFlagEnvironment.ts # toggle_flag_environment tool
│ └── removeFlagStrategy.ts # remove_flag_strategy tool
├── resources/
│ └── unleashResources.ts # MCP resource handlers (projects, flags)
├── prompts/
│ └── promptBuilder.ts # Markdown formatting utilities
├── evaluation/
│ ├── riskPatterns.ts # Risk assessment patterns
│ └── flagDetectionPatterns.ts # Parent flag detection patterns
├── detection/
│ ├── flagDiscovery.ts # Flag discovery strategies
│ └── flagScoring.ts # Scoring and ranking logic
├── knowledge/
│ └── unleashBestPractices.ts # Best practices knowledge base
├── templates/
│ ├── languages.ts # Language detection and metadata
│ ├── wrapperTemplates.ts # Code wrapping templates
│ ├── searchGuidance.ts # Pattern search instructions
│ └── cleanupGuidance.ts # Flag cleanup instructions
└── utils/
├── errors.ts # Error normalization
├── streaming.ts # Progress notifications
└── stdioLogging.ts # Stdio protocol traffic loggingThin surface area: Only the endpoints needed for the core capabilities.
Purpose-driven: Each module serves a specific, well-defined purpose.
Explicit validation: Zod schemas validate all inputs before API calls.
Error normalization: All errors converted to {code, message, hint} format.
Progress streaming: Long-running operations provide visibility.
Best practices integration: Guidance from Unleash docs embedded in tool descriptions.
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:
Create with intent: Choose the right flag type to signal purpose.
Document clearly: Write descriptions that explain the "why".
Plan for cleanup: Feature flags are temporary; plan their removal.
Monitor usage: Enable impression data for important flags.
Release flags: For gradual feature rollouts (remove after full rollout).
Experiment flags: For A/B tests (remove after analysis).
Operational flags: For system behavior (longer-lived, review periodically).
Kill switches: For emergency controls (maintain until feature is stable).
Permission flags: For access control (longer-lived, review permissions).
Use kebab-case: new-checkout-flow
Be descriptive: enable-ai-recommendations not flag1.
Include scope when needed: mobile-push-notifications.
This server uses the Unleash Admin API. For complete API documentation, see:
GET /api/admin/projects - List projects
GET /api/admin/projects/{projectId}/features - List feature flags
POST /api/admin/projects/{projectId}/features - Create feature flag
GET /api/admin/projects/{projectId}/features/{featureName} - Get flag details
POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies - Add rollout strategy
DELETE /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies/{strategyId} - Remove strategy
POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/on - Enable flag
POST /api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/off - Disable flag
Error: "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:
Align with the existing tool surface and MCP resource model.
Maintain the thin, purpose-driven architecture.
Follow Unleash best practices.
Include clear documentation.
Remove a feature flag from the codebase while preserving the desired code path.
This tool provides comprehensive step-by-step instructions for safely removing feature flag code. It guides you through:
Finding all flag occurrences using Grep
Identifying different flag usage patterns (if-else, ternary, guards, etc.)
Removing flag checks while preserving the correct code path
Cleaning up unused imports and dead code
Verifying and testing the changes
When to use this tool:
After a feature flag has been rolled out to 100% and is no longer needed
When deprecating an experimental feature (preserve disabled path)
When cleaning up technical debt from old flags
After a kill switch is no longer necessary
Preserve Path Options:
"enabled": Keep code that runs when flag is true (most common for successful feature rollouts)
"disabled": Keep code that runs when flag is false (for removed experiments or kill switches)
If not provided: You will be instructed to ask the user which path to preserve
Workflow:
Call this tool with the flag name (optionally specify which path to preserve)
If preservePath not provided, you'll be instructed to ask the user via AskUserQuestion tool
Follow the returned instructions to search and remove flag code
Clean up imports and test the changes
Report summary of changes
Safety Features:
Comprehensive pattern identification (handles if-else, ternary, guards, etc.)
Language-agnostic guidance
Post-cleanup verification steps
Test execution reminders
Import cleanup guidance
This tool is inspired by the Unleash AI flag cleanup workflow used in production. See: https://github.com/Unleash/unleash/blob/main/.github/workflows/ai-flag-cleanup-pr.yml
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Optional: Specific files to clean up. If not provided, searches entire codebase. Useful for partial cleanup or when you already know which files contain the flag. | |
| flagName | Yes | Name of the feature flag to remove (e.g., "new-checkout-flow") | |
| language | No | Optional: Programming language for specialized guidance (e.g., "typescript", "python", "go"). Auto-detected from files if not provided. | |
| preservePath | No | Optional: Which code path to preserve: "enabled" = keep code that runs when flag is true (typical for rollouts), "disabled" = keep code that runs when flag is false (for removed features). If not provided, you will be instructed to ask the user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It details the workflow: returns step-by-step instructions, may ask user if preservePath not provided, handles multiple patterns, and includes safety features. It also mentions it is language-agnostic and provides verification steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured with clear sections (workflow, safety features, preserve path options). It is front-loaded with the core purpose. Minor verbosity exists (e.g., link to workflow inspiration), but overall earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description is remarkably complete. It covers when to use each parameter, workflow steps, safety measures, and post-cleanup tasks. No gaps remain for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 4 parameters described). The description adds significant value beyond the schema: explains preservePath options and consequences, clarifies optionality of files and language, and gives example for flagName. Baseline is 3, but additional context justifies 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states precisely: 'Remove a feature flag from the codebase while preserving the desired code path.' This specific verb+resource clearly distinguishes it from sibling tools like create_flag, detect_flag, and toggle_flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to use this tool' section listing concrete scenarios (e.g., after flag rollout to 100%, deprecating experimental features). While it does not explicitly say when NOT to use, the scenarios are specific and complement sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new feature flag in Unleash.
This tool creates a feature flag with the specified configuration. Choose the appropriate flag type:
release: For gradual feature rollouts to users
experiment: For A/B tests and experiments
operational: For system behavior and operational toggles
kill-switch: For emergency shutdowns or circuit breakers
permission: For role-based access control
Best practices:
Use clear, descriptive names (e.g., "new-checkout-flow" not "flag1")
Write comprehensive descriptions explaining the flag's purpose
Choose the right type to signal intent and lifecycle
Plan for flag removal after successful rollout
See: https://docs.getunleash.io/topics/feature-flags/best-practices-using-feature-flags-at-scale
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Feature flag name (must be unique within the project). Use descriptive names like "new-checkout-flow" | |
| type | Yes | Feature flag type - determines the lifecycle and usage pattern | |
| projectId | No | Project ID where the flag will be created (optional if UNLEASH_DEFAULT_PROJECT is set) | |
| description | Yes | Clear description of what this flag controls, why it exists, and when it should be removed | |
| impressionData | No | Enable impression data collection for analytics (optional, defaults to false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the full burden. It explains the creation action and flag types but lacks disclosure of side effects, error handling, or prerequisites like permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and bullet points. It is front-loaded with the core purpose. However, it includes an external link and some redundancy in the best practices list, which could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the creation of flags with type guidance and best practices. Lacks explanation of the return value or confirmation behavior, but for a creation tool it is fairly complete given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context for flag types and best practices, which complements the schema but does not significantly enhance parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new feature flag in Unleash, and lists distinct flag types with their specific purposes. It effectively distinguishes from sibling tools like cleanup_flag or detect_flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed guidance on when to use each flag type and best practices. However, it does not explicitly state when not to use this tool compared to alternatives, missing some usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover existing feature flags in the codebase to prevent duplicates and encourage reuse.
This tool provides comprehensive search instructions for finding existing flags through multiple detection strategies:
File-based detection: Search in files being modified
Git history analysis: Find recently added flags
Semantic name matching: Match description to flag names
Code context analysis: Find flags near modification point
Use this tool when:
About to create a new feature flag
Evaluating whether a flag is needed
Want to check if similar functionality is already flagged
The tool returns detailed search instructions that guide you through:
Executing searches using Bash and Grep tools
Scoring candidates from multiple detection methods
Combining results to find the best match
Returning a confidence-scored recommendation
Workflow Integration: This tool is automatically called by 'evaluate_change' before recommending 'create_flag'. You can also call it directly when you want to search for existing flags.
Output: Returns markdown guidance with:
Step-by-step search instructions for each detection method
Scoring criteria and weight calculations
Expected JSON response format
Confidence level interpretation
After following the instructions and finding results, you should return a JSON object indicating whether a flag was found and, if so, its details with a confidence score.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Optional: List of files being modified to search for flags in the same area | |
| codeContext | No | Optional: Code context around the modification point to analyze for nearby flags | |
| description | Yes | Description of the change or feature you want to find flags for (e.g., "payment processing with Stripe") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses that the tool returns search instructions, not actual flags. It explains the multi-step process, output format, and expected user actions, making behavioral expectations completely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, strategies, usage, workflow, and output. It is somewhat verbose but every section adds value, and the front-loading of purpose is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides complete guidance: explains the tool's meta-nature, return format (markdown instructions), workflow steps, and expected final output format. It covers all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for all three parameters. The tool description adds context by relating parameters to detection strategies (e.g., files to file-based detection), enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers existing feature flags to prevent duplicates and encourage reuse, listing specific detection strategies. It distinguishes itself from sibling tools like create_flag and list_flags by describing its role as a discovery tool before creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: when about to create a new flag, evaluating necessity, or checking for similar functionality. Also mentions it's automatically called by evaluate_change before create_flag, providing clear workflow integration context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provides comprehensive guidance for evaluating whether code changes require feature flags.
This tool returns detailed evaluation guidelines including:
Workflow for systematic evaluation
Parent flag detection patterns (avoid nesting)
Risk assessment criteria
Code type evaluation (test, config, feature, etc.)
Decision tree logic
Best practices from Unleash documentation
MANDATORY next action instructions: Explicit tool call sequence (create_flag → wrap_change → implement)
Use this tool when:
Starting work on a new feature or change
Unsure if a feature flag is needed
Want guidance on rollout strategy
Need help choosing flag type
IMPORTANT WORKFLOW: When this tool determines a flag is needed, it provides explicit instructions to:
Call 'create_flag' tool to create the feature flag in Unleash
Call 'wrap_change' tool to get code wrapping guidance
Implement the wrapped code following the patterns
The tool returns markdown-formatted guidance that helps you make informed decisions and take the correct next actions.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | List of files changed (optional) | |
| branch | No | Current branch name (optional) | |
| riskLevel | No | User-assessed risk level (optional) | |
| repository | No | Repository name or path (optional) | |
| codeContext | No | Surrounding code context for parent flag detection (optional) | |
| description | No | Description of the change (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns markdown-formatted guidance and gives mandatory next actions. However, it does not explicitly state that the tool is read-only or has no side effects, which is typical for a consultative tool. Missing safety/permission context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections using bullet points and bold text. It front-loads the purpose and key workflow steps. While thorough, it could be slightly more concise by trimming redundant phrases, but overall it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an evaluation tool with multiple decision factors and no output schema, the description is fairly complete. It explains what the tool returns, when to use it, and the subsequent workflow. It could benefit from a brief example of the output format, but it sufficiently covers the agent's needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description in the schema. The tool description does not add additional meaning or examples for individual parameters beyond what the schema already provides. Hence, it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides comprehensive guidance for evaluating whether code changes require feature flags. It lists specific outputs (workflow, patterns, criteria, decision tree) and distinguishes itself from sibling tools like create_flag or wrap_change by focusing on evaluation and then directing to them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (starting a feature, unsure about flag need, need rollout guidance, choosing flag type) and includes a mandatory workflow instructing subsequent tool calls. However, it does not mention when not to use it, such as when a flag is already confirmed unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current feature flag metadata and environment strategies from the Unleash Admin API.
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | No | Project ID where the feature flag resides (optional if UNLEASH_DEFAULT_PROJECT is set) | |
| environment | No | Optional environment filter (case-insensitive) | |
| featureName | Yes | Feature flag name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only states 'Fetch' without detailing side effects, permissions, rate limits, or output format. Lacks depth for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant information, front-loaded key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet description only vaguely mentions 'metadata and environment strategies'. Missing details on return format, pagination, error handling, or data structure. Incomplete for a fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (100% coverage), so description adds minimal extra meaning. Mentions what is fetched but does not elaborate on parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses clear verb 'Fetch' and specifies resource 'feature flag metadata and environment strategies' from a known API, distinguishing it from sibling tools that create, delete, or toggle flags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like evaluate_change or toggle_flag_environment. Context only implied by the read verb, but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List feature flags in an Unleash project, with optional pagination and sort order. By default returns active flags only; set archived=true to list archived flags instead (active and archived flags are disjoint result sets in Unleash and cannot be combined in one response). Use this to discover flags before creating new ones, audit flag inventory for cleanup (call twice — once for active, once for archived), or scope a workflow to a specific project. Returns name, type, description, archived status, and URL for each flag.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of flags to return per page (default: server page size, typically 50) | |
| order | No | Sort order by flag name (default: asc) | |
| offset | No | Number of flags to skip for pagination (default: 0) | |
| archived | No | Set to true to list archived flags instead of active ones. Defaults to false (active flags only). Active and archived flags cannot be returned in the same response — call this tool twice (once with archived=false, once with archived=true) to assemble a full inventory for audit workflows. | |
| projectId | No | Project ID to list flags from (optional if UNLEASH_DEFAULT_PROJECT is set; auto-resolved when a single project exists) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the disjoint nature of active/archived, pagination support, and return fields (name, type, description, archived status, URL). Lacks depth on error behavior or authentication, but covers key behavioral traits for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, no wasted words. Front-loaded with purpose, followed by key behavioral notes, usage examples, and return fields. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description adequately explains pagination, sort, and the active/archived split. It lists return fields. Minor gaps: no mention of error states or rate limits, but core completeness is strong for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all parameters have detailed descriptions in the schema. The tool description adds no additional parameter-level semantics beyond restating the active/archived nuance already present in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'List feature flags in an Unleash project'—a specific verb and resource. It clearly distinguishes from siblings like create_flag or cleanup_flag by stating its role as a discovery/inventory tool. The name and task are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'discover flags before creating new ones, audit flag inventory for cleanup...' It also explains the need to call twice for active and archived, and notes that they are disjoint—this serves as a when-not-to-use guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Unleash projects available to the configured token, with optional pagination. Use this for discovery before scoping flag operations to a specific project. Returns project id, name, description, mode, creation time, and URL.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of projects to return per page (default: server page size, typically 20) | |
| order | No | Sort order by project creation time (default: desc, newest first) | |
| offset | No | Number of projects to skip for pagination (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool lists projects available to the token (implying auth), optionally supports pagination, and returns specific fields. However, it does not discuss rate limits, idempotency, or other behavioral details beyond what is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each serving a distinct purpose: stating the operation and providing usage guidance. No superfluous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists the fields returned. Parameters are well-documented in the schema. The tool is simple (list projects) and the description covers purpose, usage context, auth, and output. It is complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning beyond the schema—it mentions 'optional pagination' which aligns with limit/offset, and lists return fields. With high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List'), resource ('Unleash projects'), and context ('available to the configured token'), with optional pagination. It distinguishes itself from sibling flag tools by focusing on projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool for 'discovery before scoping flag operations to a specific project,' providing clear context. It does not mention when not to use it or alternative tools, but the sibling list consists entirely of flag-related tools, making its role clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a strategy configuration from a feature flag environment. Use get_flag_state to discover strategy IDs before removal.
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | No | Project ID where the feature flag resides (optional if UNLEASH_DEFAULT_PROJECT is set) | |
| strategyId | Yes | ID of the strategy to remove | |
| environment | Yes | Environment from which to remove the strategy | |
| featureName | Yes | Feature flag name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Delete' without indicating permissions, irreversibility, or side effects on the feature flag. The description lacks important behavioral context beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the main purpose, second provides a critical usage hint. No redundant or unnecessary information, making the description efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose and a key prerequisite, which is adequate for a simple 4-parameter tool. However, it omits any mention of return values (no output schema) and behavioral details like destructive nature beyond the verb 'Delete'. Completeness is functional but not enriched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters. The description adds no additional parameter meaning beyond what the schema provides. It references get_flag_state for strategy IDs but does not elaborate on parameter usage. Baseline score of 3 is appropriate given schema completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Delete a strategy configuration from a feature flag environment' with a specific verb and resource. The mention of using get_flag_state to discover IDs distinguishes related tools and provides context for when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use get_flag_state to discover strategy IDs before removal, which is a clear prerequisite. However, it does not specify when not to use this tool or alternative approaches, but the context is well-provided for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure or update a flexibleRollout strategy for a feature flag environment with an optional rollout percentage and variants. This does NOT enable the feature; call toggle_flag_environment to turn environments on or off.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional descriptive title for the strategy | |
| groupId | No | Group ID for stickiness bucketing (defaults to the feature name) | |
| disabled | No | Disable the strategy (defaults to false) | |
| variants | No | Optional list of strategy-level variants | |
| projectId | No | Project ID where the feature flag resides (optional if UNLEASH_DEFAULT_PROJECT is set) | |
| stickiness | No | Stickiness field (defaults to "default") | |
| environment | Yes | Target environment | |
| featureName | Yes | Feature flag name | |
| rolloutPercentage | Yes | Rollout percentage (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It indicates a mutation (configures/updates) and clarifies non-enablement. However, it omits details on whether the strategy is replaced or merged, permission requirements, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential: first states the core action, second clarifies a key constraint. No unnecessary words. Excellent front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and no annotations, the description is too brief. It does not explain how variants are used, what constitutes a 'flexibleRollout strategy', or return behavior. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description inaccurately describes rolloutPercentage as 'optional' when it is required in the schema. This misstatement could mislead AI agents. The description adds no other significant parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action as configuring/updating a flexibleRollout strategy for a feature flag environment. It also explicitly states what it does NOT do (enable the feature), which distinguishes it from sibling tools like toggle_flag_environment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use (for enabling features) and directs users to toggle_flag_environment instead. However, it does not address other use cases or alternatives among siblings like remove_flag_strategy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable a feature flag in a specific environment using the Unleash Admin API. For gradual rollouts, configure a flexibleRollout strategy first via set_flag_rollout.
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | Yes | Set to true to enable the flag, or false to disable it | |
| projectId | No | Project ID where the feature flag resides (optional if UNLEASH_DEFAULT_PROJECT is set) | |
| environment | Yes | Environment to toggle | |
| featureName | Yes | Feature flag name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully cover behavior. It mentions using the Unleash Admin API and the toggle action, but does not discuss side effects, idempotency, permissions, or rate limits. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first defines the core purpose, the second provides key usage guidance. No redundancy, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; the description does not explain return values or error handling. While basic usage is covered, agents lack information on what to expect after invocation, which is important for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter details are already provided. The description reiterates enabling/disabling but adds little new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'enable or disable' and the resource 'feature flag in a specific environment', providing a specific action on a distinct resource. It distinguishes from sibling tools by referencing set_flag_rollout for gradual rollouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when not to use this tool (for gradual rollouts, use set_flag_rollout). It implies the appropriate use case (simple enable/disable), though it could explicitly state 'use for toggling entire environment'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate code snippets and guidance for wrapping changes with feature flags.
⚠️ CRITICAL: This tool enforces RUNTIME-CONTROLLABLE feature flags. You MUST place flag checks INSIDE execution paths (handlers, functions), NOT wrapping route registrations, middleware mounting, or controller registration.
This tool provides language-specific templates and instructions for protecting code changes with feature flags. It helps you:
Find existing feature flag patterns in your codebase
Match detected conventions (imports, method names, wrapping styles)
Generate appropriate code snippets for your language/framework
Follow Unleash SDK best practices
Ensure flags are runtime controllable (toggle without redeploy)
Supported languages:
TypeScript/JavaScript (Node, React, Vue, Angular)
Python (FastAPI, Django, Flask)
Go
Ruby (Rails)
PHP
C# (.NET)
Java (Spring Boot)
Rust
The tool uses a prompt-based approach: it provides detailed instructions for searching your codebase for existing patterns and matching their conventions. If no patterns are found, it provides sensible defaults based on Unleash SDK documentation.
Usage:
Call this tool with the flag name after creating a flag
Follow the search instructions to find existing patterns
Use the recommended template or match detected patterns
Test your implementation
Best suited for use after evaluate_change recommends a flag and create_flag creates it.
| Name | Required | Description | Default |
|---|---|---|---|
| fileName | No | File name being modified (helps detect language, e.g., "checkout.ts") | |
| flagName | Yes | Feature flag name to wrap the code with (e.g., "new-checkout-flow") | |
| language | No | Programming language (optional, auto-detected from fileName). Supported: typescript, javascript, python, go, ruby, php, csharp, java, rust | |
| codeContext | No | Optional: surrounding code to help detect existing patterns | |
| frameworkHint | No | Optional: framework hint for specialized templates (React, Express, Django, Rails, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool provides language-specific templates, searches for patterns, and uses a prompt-based approach. However, it doesn't detail side effects, limitations, or whether external calls are made.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections and bullet points. Some redundancy exists, but it is efficiently organized for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fails to explain what the tool returns (e.g., code snippets, instructions). This is a significant gap, as the agent needs to know how to use the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have basic descriptions. The description adds operational context (e.g., language auto-detection from fileName) but doesn't significantly enhance meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool generates code snippets and guidance for wrapping changes with feature flags, a specific action on a specific resource. It distinguishes from sibling tools like create_flag and detect_flag by focusing on the wrapping process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage steps and a critical warning about flag placement. It also advises when to use this tool in the workflow (after evaluate_change and create_flag). However, it doesn't explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0cleanup_flagcreate_flagdetect_flagevaluate_changeget_flag_statelist_flagslist_projectsremove_flag_strategyset_flag_rollouttoggle_flag_environmentwrap_changeScored across 11 tools
Each tool serves a unique and clearly defined purpose in the feature flag lifecycle (creation, evaluation, detection, state, listing, strategy, toggling, cleanup, wrapping), with no overlapping functionality.
All tool names follow a consistent verb_noun snake_case pattern (e.g., cleanup_flag, create_flag, toggle_flag_environment), making predictions easy.
With 11 tools, the server covers the full lifecycle of feature flag management without being bloated; each tool is justified and valuable.
Covers almost all aspects: evaluation, detection, creation, state, listing, rollout, toggling, strategy removal, code wrapping, and cleanup. Missing explicit flag deletion from the admin API, but cleanup may subsume that.
Evaluate and inspect your Hypertune feature flags from your AI assistant.
Connect AI agents to CloudBees Unify: feature flags, CI/CD, release orchestration, and security
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
