Unleash MCP Server

Unleash MCP Server

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

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

Overview

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

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

Available tools

The MCP server exposes the following tools:

• create_flag: Creates a feature flag in Unleash.
• evaluate_change: Scores risk and recommends feature flag usage.
• detect_flag: Discovers existing feature flags to avoid duplicates.
• wrap_change: Provides guidance on how to wrap a change in a feature flag.
• set_flag_rollout: Sets who gets a feature flag in each environment: rollout percentage, segments, constraints, and whether the environment is on.
• get_flag_state: Surfaces a feature flag's metadata and its activation strategies.
• get_flag_history: Returns a feature flag's recent changes from the event log, each as a diff of what changed, who changed it, when, and in which environment.
• evaluate_flag: Evaluates a single feature flag against an Unleash context (for example a user ID and custom properties) in an environment, and explains which strategies matched.
• list_flags: Lists all feature flags in a project, with optional pagination and sort order.
• search_flags: Searches active feature flags in all projects by part of their name or description, or finds one flag and its project by its full name.
• 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.
• send_feedback: Reports a failed tool call, an unsupported request, or an unexpected result to Unleash so the MCP can be improved. Requires the user's consent. Not listed when consent is denied up front through UNLEASH_MCP_SEND_FEEDBACK=false or the feedbackConsent server option.

Core workflow

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

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

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

Prerequisites

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

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

Get started

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

Agent setup

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

For Claude Code:

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

For Codex:

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

Remote agent setup (experimental)

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

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

OAuth

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

For Claude Code:

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

For Codex:

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

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

The PAT expires after 24 hours by default.

Personal Access Token (PAT)

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

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

For Claude Code:

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

For Codex:

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

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

Quickstart with npx

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

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

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

Local development setup

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

1. Install dependencies

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

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

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

pnpm install

1. Run in dev mode directly from Claude or Codex

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

A) Use compiled JS (most reliable)

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

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

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

B) Use TypeScript directly (no build)

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

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

Notes:

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

Logging control

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

Client attribution

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

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

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

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

Tool reference

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

Create flag

The create_flag tool creates a new feature flag in Unleash with comprehensive validation and progress tracking.

When to use

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.

Parameters

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).

Usage example

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, its MCP resource URI, creation timestamp, and configuration details.

Evaluate change

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.

When to use

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.

How it works

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:

1. Call create_flag tool to create the feature flag.
2. Call wrap_change tool to get language-specific code wrapping guidance.
3. 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', () => {...})

Parameters

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.

Usage example

Agent prompt

Simple usage where you let the agent gather context:

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

Explicit 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
}

Detect flag

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.

When to use

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.

How it works

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 score

Confidence 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.

Parameters

• 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.

Usage example

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 flags

Tool 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
}

Wrap change

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.

When to use

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).

How it works

This tool is the final step in the evaluate_change → create_flag → wrap_change workflow.

The tool provides the following guidance in its response:

1. Search instructions: Step-by-step guide for finding existing flag patterns in your codebase using grep.
2. Pattern detection: Identifies common patterns (for example, imports, client variable names, method names, or wrapping styles).
3. Default templates: Fallback code snippets if no patterns are found.
4. Framework-specific examples: Specialized patterns for React, Express, Django, and others.
5. 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.

Parameters

• 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".

Usage example

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.]

Set flag rollout

The set_flag_rollout tool sets who gets a feature flag in one or more environments: a rollout percentage, optionally narrowed to segments and to constraints on context fields, and whether each environment is on.

It checks the whole request before changing anything: every environment, segment name, context field and constraint value. When a segment name or the strategy to change is unclear, it asks the user to pick from a list, if the MCP client can show forms. Otherwise the error lists the valid options for the agent to put to the user.

In each environment:

• With no strategies, it adds a flexibleRollout strategy when the entry sets any strategy field. The rollout defaults to 100% of the targeted users, and stickiness defaults to default. An entry with only enabled: true adds nothing, so Unleash gives the environment the project's default strategy.
• With one flexibleRollout strategy, it updates that strategy. Fields you leave out keep their value, so { rolloutPercentage: 100 } moves a rollout to 100% and keeps its segments, constraints, stickiness and variants.
• With several, it needs strategyId.
• It saves the strategy before turning the environment on, so Unleash doesn't add the project's default strategy next to it. Turning an environment off happens before the save, so the new strategy never goes live there.
• Turning on an environment whose strategies are all disabled turns them all back on.

When to use

Use it after create_flag to roll the flag out, and later to change who gets it, such as moving from 30% to 100%.

Parameters

• featureName (required): Feature flag name.
• projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).
• environments (required): One entry per environment, each with:
  • environment (required): Environment name, such as "production".
  • rolloutPercentage (optional): Percentage of the targeted users who get the flag (0-100).
  • segments (optional): Segment names, as the user said them. Case, spaces and hyphens don't matter. [] removes all segments.
  • constraints (optional): Constraints, each with contextName, operator (any Unleash constraint operator), values or value, inverted and caseInsensitive. [] removes all constraints.
  • strategyId (optional): The strategy to change when the environment has more than one.
  • stickiness (optional): Stickiness field. A new strategy uses "default".
  • groupId (optional): Group ID for stickiness bucketing. A new strategy uses the flag name.
  • title (optional): Descriptive title for the strategy.
  • strategyDisabled (optional): Pause the strategy without deleting it. This is not the same as enabled: false, which turns the flag off in the environment.
  • variants (optional): Strategy variants, each with name, weight (0-1000), weightType, stickiness and payload. [] removes all variants.
  • enabled (optional): Turn the environment on or off. true also turns on the strategy if it was disabled, unless strategyDisabled is passed.

Usage example

Agent prompt

Turn on new-checkout-flow in development, and roll it out to 30% of beta users in production.

Tool payload

{
  "featureName": "new-checkout-flow",
  "projectId": "ecommerce",
  "environments": [
    { "environment": "development", "enabled": true },
    {
      "environment": "production",
      "rolloutPercentage": 30,
      "segments": ["beta users"],
      "enabled": true
    }
  ]
}

Tool output

For each environment, it returns whether the strategy was added, updated or left unchanged, whether the environment is on, and the saved rollout percentage, segment names and constraints. An update also shows the previous values. Notes flag anything that limits the rollout, such as the environment being off or other strategies that still apply. The result also links to the flag in the Unleash Admin UI, the Admin API and the flag's MCP resource URI.

Errors

If the request has problems, nothing is changed. The error code is INVALID_ROLLOUT, and problems lists every problem at once, each with its environment, code, message, hint and, where there are any, the valid options:

Other errors:

• VALIDATION_ERROR for a field the tool doesn't know, such as a misspelt one, so it is never ignored.
• HTTP_404 when the flag is not in the project. The hint points to create_flag and search_flags.
• If saving fails partway through, the error keeps Unleash's code and adds failedEnvironment, applied (the environments that were saved) and notChanged.

Get flag state

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 each environment's strategies and variants.

When to use

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.

Parameters

• featureName (required): Feature flag name.
• projectId (optional): Project ID (defaults to UNLEASH_DEFAULT_PROJECT).
• environment (optional): Filter results to a single environment (case-insensitive).
• includeSegments (optional): Also return the segments that the strategies in the matching environments use.
• includeContextFields (optional): Also return the context fields that constraints in the flag's project can use.

Usage example

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 JSON object with the full feature object (all environments and strategy details), the environments matching the filter, and UI and API links.

Strategies list their segments only by ID. When the matching environments use segments, the output includes a hint naming them. With includeSegments, it instead includes segments, each with its id, name, description, project, and the constraints that decide who it includes. Segments that could not be fetched are listed under segmentErrors, each with the error Unleash gave, and do not fail the call.

With includeContextFields, the output includes contextFields: the root context fields plus the project's own, each with its name, description, legalValues, whether it can set rollout stickiness, and the project it belongs to if it is project-specific.

Evaluate flag

The evaluate_flag tool evaluates a single feature flag against an Unleash context in an environment, using the Unleash playground API. It returns whether the flag is enabled for that context, the variant it resolves to, and a per-strategy breakdown listing the constraints and segments that did not match. The project is resolved from the flag name.

Alpha: this tool uses POST /api/admin/playground/features/{featureName}, an alpha Unleash API that may change. It requires an Unleash version that provides this endpoint.

When to use

Use this tool to answer questions like "is show-new-checkout on for user asdf?" or to debug why a flag is off for a specific user. Use get_flag_state to inspect a flag's configuration instead.

Parameters

• featureName (required): Feature flag name.
• environment (optional): Environment to evaluate in (defaults to UNLEASH_DEFAULT_ENVIRONMENT; required if that is not set).
• context (optional): A flat Unleash context object. userId, sessionId, remoteAddress, currentTime, and appName are sent as standard fields; any other key (for example tier) is sent as a custom context property. Numbers and booleans are converted to strings. A nested properties object is also accepted.
• appName (optional): Application name for the context (default: unleash-mcp).

Usage example

Agent prompt

Use evaluate_flag to check whether "show-new-checkout" is enabled in production
for userId "asdf" on the "top" tier.

Tool payload

{
  "featureName": "show-new-checkout",
  "environment": "production",
  "context": { "userId": "asdf", "tier": "top" }
}

Tool output

Returns a text summary with the result (ENABLED, DISABLED, or UNKNOWN when a custom strategy cannot be evaluated), the variant, warnings when the flag is off in the environment or has an unsatisfied dependency, each strategy's outcome with its failing constraints and segments, the context that was sent, and a link to the flag in the Unleash Admin UI. The structured output includes the full playground response.

Get flag history

The get_flag_history tool fetches the most recent change events for a feature flag from the Unleash event log, newest first. Instead of returning each event's full before and after payloads, it computes a structural diff inside the tool and returns only the changed fields, so the agent reads the change itself without having to diff two large objects.

When to use

Use this tool before editing or toggling a flag to see what changed recently and who changed it, or to explain why a flag is in its current state. Pair it with get_flag_state when the current configuration alone does not answer the question.

Parameters

• featureName (required): Feature flag name.
• limit (optional): Maximum number of most recent changes to return, between 1 and 100 (default: 20).

Usage example

Agent prompt

Use get_flag_history with:
- featureName: "new-checkout-flow"
- limit: 10

Tool payload

{
  "featureName": "new-checkout-flow",
  "limit": 10
}

Tool output

Returns a JSON object with featureName, total (every change on record for the flag), and events. Each event has createdAt, createdBy, type, environment, and changes: a list of changed leaves with path (for example ["parameters", "rollout"]), before, and after. Added fields have before: undefined, removed fields have after: undefined. Fields that change on their own, such as createdAt and lastSeenAt, are stripped from the diff. Events with no payload, such as enabling or disabling an environment, have an empty changes list; the type describes them. When total is larger than the number of events returned, raise limit.

List flags

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.

When to use

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).

Parameters

• 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).

Usage example

Agent prompt

Use list_flags with:
- projectId: "ecommerce"
- archived: false

Tool payload

{
  "projectId": "ecommerce",
  "archived": false,
  "limit": 50,
  "order": "asc"
}

Tool output

Returns a JSON object 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.

Search flags

The search_flags tool searches active feature flags in all projects by part of their name or description. Given a flag's full name, it returns that flag and the project it is in, which the other flag tools need as projectId.

Parameters

• query (required): Part of a flag name or description, or a full flag name.

Tool output

Returns a JSON object with total, the number of matching flags, and flags. Each flag has its name, project, type, description, whether it is stale, and whether it is enabled in each environment. When total is larger than the number of flags returned, a longer query narrows the results.

List projects

The list_projects tool enumerates the Unleash projects available to the configured token, with pagination and sort order.

When to use

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).

Parameters

• 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).

Usage example

Agent prompt

Use list_projects to see which projects are available.

Tool payload

{
  "limit": 20,
  "order": "desc"
}

Tool output

Returns a JSON object with order, limit, offset, nextOffset, totalProjects, and the projects array (each with id, name, description, creation time, and URL).

Toggle flag environment

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.

When to use

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.

Parameters

Documentation truncated — see the full README on GitHub.