Unleash MCP server | Unleash Docs

The Unleash Model Context Protocol (MCP) server lets AI agents work with Unleash the way you work in the Unleash UI: find flags, release them, check who gets them, and see what changed.

The Unleash MCP server works with any MCP client, including coding assistants such as Claude Code, Codex, Cursor, Copilot, Kiro, OpenCode, and with agents that run outside an editor.

Overview

Instead of mirroring every API operation as a tool, the server exposes a small set of tools organized around outcomes. Each tool does a complete job, such as “releasing a flag to 10% of users”, so the agent doesn’t have to work out the order of several API calls. This keeps the agent’s context small and reduces guesswork.

The server provides tools for the following:

Release features safely: Roll out a flag to audiences, split by value, or through a release template.
Protect long-lived features: Turn a permanent kill switch on or off.
Run experiments: Split audiences across values, such as control and treatment, for A/B tests.
Explore your feature management setup: Look up projects, flags, segments, context fields, and tags before acting on them.
Debug targeting: Check why a user gets or doesn’t get a flag.
Manage your inventory: Create segments, context fields, tags, release templates, and projects, and manage flag properties and lifecycle.
Review changes: Read the audit log of who changed what and when.
Answer questions about Unleash: Point the agent to the Unleash documentation for guidance on practices and concepts.

For the list of tools, with a description and an example prompt for each, see the README on GitHub.

The Unleash MCP server respects your existing access controls. It acts with the permissions of the user or service account behind the access token. Where an environment requires change requests, the server submits one instead of applying the change directly. See Change requests and approvals.

Get started

You can connect to the Unleash MCP server in two ways:

Remote MCP server: Hosted by your Unleash instance. You don’t install or run anything on your machine. Use this setup if you want a single, managed entry point for all clients, or if developers can’t install MCP servers on their laptops.
Local MCP server: Runs on your machine as a process that your MCP client starts. Use this setup if you don’t have access to the remote server, such as on Unleash Open Source or on a plan without it.

After you connect the server, follow the setup guide for your client for client-specific details such as approval settings and enterprise configuration:

To check that the server works, ask your agent: “List my Unleash projects”.

Remote MCP server

Enterprise

The remote MCP server lets MCP clients connect to a Streamable HTTP MCP server hosted by your Unleash instance, without installing anything locally. This is useful when developers can’t run MCP servers on their laptops, or when you want to manage MCP access centrally.

When enabled, your Unleash instance exposes an MCP endpoint at:

https://<your-instance-url>/api/admin/mcp

The remote MCP server exposes the same tools as the local server. For feedback reports, an admin decides for the whole instance instead of each user opting in. See Feedback from the remote server.

Enable the remote MCP server

To enable the remote MCP server on your instance:

Hosted

Self-hosted

In the Admin UI, go to Admin settings > Remote MCP server.
Toggle Enable Remote MCP Server for this instance to Enabled.
Optional: To turn off feedback reports, toggle Send feedback from the Remote MCP Server to Unleash to Disabled.
Save the configuration.

Only enable the remote MCP server if your organization allows the OAuth 2.0 Dynamic Client Registration (DCR) authorization workflow. DCR lets MCP clients self-register with your instance without prior administrator approval, which is required to support clients such as Claude Code that do not pre-register OAuth clients. Review your organization’s policy before enabling this.

Connect a client

Point your MCP client at the endpoint shown in Admin settings > Remote MCP server. You don’t need an OAuth client ID or client secret. MCP clients register themselves with your instance the first time they connect.

Authenticate with one of the following options:

Personal access token

Service account token

Use this option if you are a developer connecting your own coding assistant.

Configure your client without a token. When the client first connects, it opens your browser so you can log in to Unleash with your usual credentials. Unleash then issues a personal access token that is valid for 24 hours, and your client uses it for all MCP requests. The token has the same permissions as your user. After 24 hours, log in again to get a new token.

Leave any client ID and client secret fields in your client empty.

Unleash only redirects back to localhost after login, so this option works with command-line clients such as Claude Code, but not with hosted clients such as Claude Desktop or Claude on the web.

For example, in Claude Code:

claude mcp add --transport http unleash https://<your-instance-url>/api/admin/mcp

Then run /mcp in Claude Code and select unleash to log in.

For Codex, add the server and then log in:

codex mcp add unleash --url https://<your-instance-url>/api/admin/mcp
codex mcp login unleash

Feedback from the remote server

v8.3

For the remote MCP server, an admin turns feedback reports on or off for the whole instance. Users don’t see a consent prompt.

To change the setting, go to Admin settings > Remote MCP server and toggle Send feedback from the Remote MCP Server to Unleash. The setting is enabled by default, including on existing instances after you upgrade, and only takes effect while the remote MCP server is enabled.

When the setting is enabled, the remote server shares the same anonymous diagnostic reports as the local server. See What is recorded. When the setting is disabled, MCP clients don’t see the send_feedback tool.

Run the MCP server locally

The local server runs as a process on your machine that your MCP client starts and talks to over standard input and output (stdio). It calls your Unleash instance with a personal access token.

Prerequisites

Before you start, make sure you have the following:

Node.js 24 or later: The server is distributed as an npm package.
An Unleash instance: Hosted or self-hosted.
A service account with token or personal access token, as the server acts with the permissions of the user who owns the token.

Add the MCP server to your client

For Claude Code, run the following command from the project where you want to use the server:

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

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

For clients configured with JSON, add the MCP server to the client’s MCP servers:

{
  "mcpServers": {
    "unleash": {
      "command": "npx",
      "args": ["-y", "@unleash/mcp@latest"],
      "env": {
        "UNLEASH_BASE_URL": "{{your-instance-url}}",
        "UNLEASH_PAT": "{{your-personal-access-token}}"
      }
    }
  }
}

The exact file and format depend on your client. See the setup guide for your client in Get started.

To opt in to or out of feedback reports without a consent prompt, set UNLEASH_MCP_SEND_FEEDBACK to true or false in the same env configuration.

Configuration

Variable	Required	Description
`UNLEASH_BASE_URL`	Yes	The URL of your Unleash instance, such as `https://your-instance.getunleash.io`. Don’t include `/api`.
`UNLEASH_PAT`	Yes	The personal access token the server calls Unleash with.
`UNLEASH_MCP_SEND_FEEDBACK`	No	Set to `true` to send feedback reports without asking, or `false` to turn them off. Unset, you’re asked on the first report.
`UNLEASH_FEEDBACK_URL`	No	The Unleash instance that receives feedback reports. By default, reports go to Unleash. See Send reports to your own endpoint.
`UNLEASH_MCP_CONFIG_DIR`	No	The directory that stores your feedback answer in `feedback_consent.json`. Defaults to your platform’s configuration directory.

To keep secrets out of your client configuration, store the variables in an environment file and start the server with node --env-file=.env. This requires running the server from a local copy of the repository instead of through npx. See the README for the steps.

Workflows

The following workflows show what you can ask an agent to do. The agent chooses and combines the tools. You don’t name them in your prompts.

Before it changes anything, an agent usually looks up the values it needs, such as project IDs, segment IDs, and context fields. The search and inspect tools provide the same options that the Unleash UI shows in its dropdowns. You can say “the checkout project” and the agent finds the matching ID.

If the flag doesn’t exist, the server creates it in a switched-off state. To turn a flag on in an environment, ask the agent to enable it explicitly or release it gradually.

Release a feature gradually

Ask the agent to release a flag to a share of users in one environment:

“Roll out new-checkout to 10% of users in production.”
“Release new-checkout to the beta-testers segment in staging, then to 25% of everyone else.”
“Release new-checkout in production using the standard rollout template.”

The agent describes the end state of the release for that environment, and the server replaces the environment’s existing targets with it. Each audience in a release has a name that says why it exists, for example “Beta testers”.

Add a kill switch

Ask the agent to turn a permanent kill switch on or off, for everyone or for selected audiences:

“Turn off payments in production.”

If the kill switch doesn’t exist, the server creates it as a permanent flag of the kill switch type. A name that describes the disabled state, such as disable-payments, makes the switch easier to read.

Run an A/B test

Ask the agent to split an audience across values, or to give each audience its own value:

“Split checkout 50/50 between control and the new flow.”

If the flag doesn’t exist, the server creates it as an experiment flag that reports impression data. The MCP server sets up the split. It doesn’t analyze the results, and it doesn’t end the experiment for you.

Check who gets a feature

Ask the agent to evaluate a flag in an environment, with a context such as a user ID or country:

“Does user 42 get new-checkout in production?”
“Why isn’t user 42 seeing new-checkout in staging?”

This is the agent equivalent of the Unleash playground. The result tells you whether the flag is enabled, disabled, or unknown for the context, and explains each target in the order Unleash checks them: which segments and constraints matched or missed, and what rollout percentage applied. If a parent flag or the environment turns the flag off, the result says so.

A result of unknown means a target uses a custom strategy that only an SDK can evaluate.

Look up and manage your inventory

Ask the agent to find things, or to prepare them before a release:

“Which flags in the checkout project are tagged team:payments?”
“Show me everything about the new-checkout flag.”
“Create a beta-testers segment for userId 1, 2, and 3.”
“Make new-checkout depend on the payments-v2 flag.”
“Archive the old-banner flag.”

Review what changed

Ask the agent what changed, who changed it, and when:

“What changed in production yesterday?”
“Show me the history of new-checkout this week.”

A search covers at most 31 days and defaults to yesterday and today.

Ask about Unleash

Ask the agent a question about Unleash practices or concepts, such as how to add the SDK to a framework or which flag type to use. The docs tool gives the agent the index of the Unleash documentation, and the agent reads the pages that answer your question.

Clean up stale flags

The server helps you find stale flags and record their outcome in Unleash. Your agent removes the flag from the code using its own knowledge of your codebase, with the Unleash documentation for guidance.

Find stale flags

Ask the agent to list flags that are stale or potentially stale in a project. Unleash marks a flag as potentially stale when it passes its expected lifetime.

“List the stale and potentially stale flags in the checkout project.”

Check each flag

Ask the agent to inspect a flag before you act on it. The agent can see the environments where the flag is enabled, when SDKs last reported it, its parent and child flags, and any pending change requests.

“Is it safe to remove the old-banner flag? Check where it’s enabled and when it was last used.”

Record how the rollout ended

Ask the agent to record whether you kept or discarded the feature. If you kept it and tried several values, the agent records the value you kept. You can also confirm or override the stale marking. These are notes for your team and don’t change what SDKs receive.

Remove the flag from the code

Ask the agent to remove the flag and the code path you no longer need. Review and deploy the change as usual.

Archive the flag

After the code change is live, ask the agent to archive the flag. Archived flags are no longer served to SDKs, which treat them as off, so archive a flag only after no code evaluates it. In an environment with change requests, archiving creates one.

Change requests and approvals

AI agents can make mistakes. When you turn on change requests for an environment, the server follows them automatically:

Tools that change an environment, such as releases, kill switches, and experiments, put the change into a change request instead of applying it.
The agent receives the change request ID, its state, and a link to it in the Unleash UI. It passes the link to you.
You review, approve, and apply or schedule the change request in Unleash. The server can’t approve or apply it. These steps remain with a human, intentionally.
When the agent inspects a flag, it sees pending change requests, so it doesn’t mistake a waiting change for an applied one or request it again.

You don’t have to ask the agent to create a change request.

When you have an open draft change request, Unleash adds the agent’s change to your draft. The MCP server then submits the whole draft for review, including any changes you made yourself.

Enable change requests on any environment where unreviewed changes pose a risk, especially production. For configuration steps, see change requests.

Limits

The server is designed to cover the common cases in a token-efficient way. Some operations stay in the Unleash UI or in the API:

Approvals and access control: You approve change requests, and manage users, roles, and tokens, in the UI.
Flag deletion: The server archives and revives flags but doesn’t delete them, because you can’t undo a deletion.
Other activation strategies: Releases write gradual rollouts. If an environment has other kinds of targets, such as user ID lists or IP addresses, the server refuses to change that environment’s targets and asks you to change them in the UI.
Experiment results: The server sets up an experiment but doesn’t analyze its results.
Audit history: A search covers at most 31 days, in pages of 25 changes.

Send feedback

The send_feedback tool shares anonymous diagnostic reports with Unleash to help improve the MCP server. Unleash uses these reports to prioritize fixes and new tools.

You don’t call this tool yourself. The assistant calls it automatically.

When feedback is sent

The assistant sends a report before it replies to you in the following cases:

tool_error: A tool call returns an error.
unsupported_action: You ask for something the MCP server can’t do yet.
unexpected_result: A tool call succeeds, but the result isn’t what the assistant expected.
unanswered_question: You ask about Unleash and the documentation pages the assistant read don’t answer it.

The assistant doesn’t send a report for authentication errors (HTTP 401 or 403), or when send_feedback itself fails.

The local MCP server sends feedback reports only after you opt in. The first time the assistant calls send_feedback, your client shows a consent prompt. What happens next depends on your response:

You accept: The MCP server sends the report and saves that you opted in. You don’t see the prompt again.
You decline: The MCP server doesn’t send the report and saves that you opted out. You don’t see the prompt again.
You cancel or don’t respond within 60 seconds: The MCP server doesn’t send the report and doesn’t save anything. You see the prompt again in your next session.

In some clients, you don’t see the consent prompt. See Clients without a consent prompt.

The MCP server saves whether you opted in or out in a file named feedback_consent.json. All clients on your machine that show the consent prompt read this file, so you respond to the prompt only once. The file is in your platform’s configuration directory:

macOS

Linux

Windows

~/Library/Application Support/unleash-mcp/feedback_consent.json

If you set XDG_CONFIG_HOME, the file is in $XDG_CONFIG_HOME/unleash-mcp/ instead.

To store the file in a different directory, set UNLEASH_MCP_CONFIG_DIR. To see the prompt again, delete the file.

To skip the prompt, set UNLEASH_MCP_SEND_FEEDBACK to true or false. The variable takes precedence over feedback_consent.json. With false, the assistant doesn’t see the send_feedback tool. Use the variable for CI and for centrally managed MCP configuration.

The remote MCP server doesn’t show a consent prompt. Instead, an admin turns feedback reports on or off for the whole instance. See Feedback from the remote server.

In the following clients, you don’t see the consent prompt. To opt in or out, set UNLEASH_MCP_SEND_FEEDBACK to true or false.

OpenCode

Antigravity and Gemini CLI

Codex

Other clients

OpenCode accepts the consent prompt automatically, without showing it to you. Because the MCP server can’t be sure that you opted in yourself, it doesn’t request the prompt and ignores feedback_consent.json.

Feedback reports stay off until you set UNLEASH_MCP_SEND_FEEDBACK=true. See OpenCode.

What is recorded

Each report contains only the following fields:

Issue type, the name of the tool involved, and the status and error name of a failed result
MCP server version, client name, and client version
A short summary that the assistant writes

The tool name is chosen from a fixed list, and the error name follows a fixed format, so neither can contain free text. The assistant is instructed to leave flag names, project IDs, code, URLs, and tokens out of the summary. Reports never include raw error messages or your personal access token.

By default, reports go to Unleash, not to your Unleash instance. To send them to your own endpoint instead, see Send reports to your own endpoint. See also Data and privacy.

Send reports to your own endpoint

To collect feedback reports yourself instead of sending them to Unleash, set UNLEASH_FEEDBACK_URL to the base URL of your endpoint, for example https://feedback.example.com. The URL must start with http:// or https://.

The MCP server then sends each report as a POST request to {UNLEASH_FEEDBACK_URL}/feedback with a JSON body. The areasForImprovement field holds the report fields from What is recorded as a JSON-encoded string:

{
  "category": "mcp",
  "areasForImprovement": "{\"issueType\":\"tool_error\",\"summary\":\"Releasing the flag failed with a server error.\",\"tool\":\"release\",\"error\":{\"status\":500,\"name\":\"ServerError\"},\"mcpVersion\":\"2.0.0\",\"client\":\"claude-code\",\"clientVersion\":\"2.1.80\"}"
}

Reports sent to your own endpoint don’t reach Unleash. Consent works the same way: the MCP server sends reports only after you opt in.

Migrate from version 0.5

Version 2 of the Unleash MCP server replaces the tools of version 0.5 with a smaller set built around outcomes. It also changes the requirements:

Node.js 24 or later: Version 0.5 required Node.js 20 or later.
No UNLEASH_DEFAULT_PROJECT: The agent looks up the project instead.
No command-line flags: The --log-level and --dry-run flags are removed.
No code-aware guidance in the server: The server no longer generates code wrapping templates or cleanup instructions. The agent uses its own knowledge of your language and framework, and the Unleash documentation, instead.

Use the following table to find the closest equivalent of each tool in version 0.5:

Version 0.5 tool	Closest equivalent now
`evaluate_change`	The agent decides whether a change needs a flag, guided by the documentation and your team’s skills.
`detect_flag`	`search` for existing flags by name or tag.
`create_flag`	`release`, `kill_switch`, and `experiment` create a missing flag. `manage_flag` defines a flag without releasing it.
`wrap_change`	The agent writes the code, using the Unleash SDK documentation.
`list_projects`, `list_flags`	`search`
`get_flag_state`	`inspect`
`set_flag_rollout`, `toggle_flag_environment`, `remove_flag_strategy`	`release` describes the end state of an environment, including turning a flag off.
`cleanup_flag`	`manage_flag` records the outcome and archives the flag. The agent removes the code. See Clean up stale flags.
`send_feedback`	`send_feedback`. See Send feedback.

To keep using version 0.5, pin it in your client configuration: npx -y @unleash/mcp@0.5.0.

Troubleshooting

The server returns failures to the agent as text, so the agent usually tells you what went wrong.

The agent can’t connect to the server: Check that UNLEASH_BASE_URL is a complete URL that includes the protocol, such as https://your-instance.getunleash.io, without /api at the end. Check that UNLEASH_PAT is set. For the local server, run node --version and confirm it’s 24 or later.

Unauthorized (HTTP 401): Your token is invalid or has expired. Create a new token under Profile > View profile settings > Personal API tokens. For the remote server with browser login, log in again to get a new 24-hour token.

Forbidden (HTTP 403): Your token doesn’t have permission for this action. Review the role and permissions of the user or service account in Unleash.

Not found (HTTP 404): The project, flag, or environment doesn’t exist, or you can’t see it. Ask the agent to search for the correct name first.

A change didn’t take effect: Check whether the environment requires change requests. The change might be waiting for approval in Unleash. Ask the agent to inspect the flag to see pending change requests.

“Feedback is disabled”: You declined the consent prompt, your client couldn’t show it, or UNLEASH_MCP_SEND_FEEDBACK is set to false. To opt in, set UNLEASH_MCP_SEND_FEEDBACK=true. To see the prompt again, delete feedback_consent.json. See Consent. Feedback settings don’t affect flag operations.