Unleash MCP Server

Unleash MCP server

An MCP server that lets AI agents work with Unleash the way you'd work in the Unleash UI: find flags, roll them out, check who gets them, and see what changed. It's in alpha and isn't published to npm, so you run it from source.

Tools

Install locally

You need Node 24 or later and pnpm.

1. Clone the repository and switch to the v2 branch:

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

   This gets you the v2 source.

2. Install the dependencies:

   pnpm install
   

   Node runs the TypeScript source directly, so there's no build step.

3. In Unleash, create a personal access token under Profile > Personal API tokens. The server acts with that user's permissions.

4. Register the server with your MCP client. For Claude Code:

   claude mcp add unleash \
     -e UNLEASH_BASE_URL=https://your-instance.getunleash.io \
     -e UNLEASH_PAT=user:your-personal-access-token \
     -- node /absolute/path/to/unleash-mcp/src/index.ts
   

   This adds a stdio server named unleash to Claude Code. For clients configured with JSON, such as Claude Desktop, Cursor or VS Code, add this to their MCP servers:

   {
     "mcpServers": {
       "unleash": {
         "command": "node",
         "args": ["/absolute/path/to/unleash-mcp/src/index.ts"],
         "env": {
           "UNLEASH_BASE_URL": "https://your-instance.getunleash.io",
           "UNLEASH_PAT": "user:your-personal-access-token"
         }
       }
     }
   }
   

5. Ask your agent "List my Unleash projects". If it answers with your projects, the server is running.

Configure the local server

send_feedback sends anonymous reports to Unleash when the server fell short: a tool error, a request no tool supports, or a wrong result. A report names the tool, the error and the MCP client the agent runs in. Say yes to help us fix what doesn't work for you.

Nothing is sent until you agree. The first report asks you through your MCP client, and your answer is kept in feedback_consent.json, so you're asked once. The file sits in an unleash-mcp directory under $XDG_CONFIG_HOME when it's set, otherwise under ~/Library/Application Support on macOS, %APPDATA% on Windows and ~/.config on Linux. Delete it to be asked again.

If you dismiss the question, or your client can't show it, feedback stays off until the next session. OpenCode, Gemini and Antigravity never show it, so there feedback stays off unless UNLEASH_MCP_SEND_FEEDBACK is true.

To keep secrets out of your client config, copy .env.example to .env, fill it in, and start the server with node --env-file=.env /absolute/path/to/unleash-mcp/src/index.ts.

Connect to the remote server

Unleash Enterprise hosts this server, over Streamable HTTP, so nothing runs on your machine. An admin turns it on under Admin > Remote MCP Server; send_feedback reports are sent unless the admin turns them off there.

Register the server with your MCP client. For Claude Code:

claude mcp add unleash https://your-instance.getunleash.io/api/admin/mcp --transport http

For Codex, add the server and then log in:

codex mcp add unleash --url https://your-instance.getunleash.io/api/admin/mcp
codex mcp login unleash

The login opens your browser to log in to Unleash; Claude Code does the same on first use. Unleash then creates a personal access token for the client, valid for 24 hours, and the server acts with your permissions.

Where a browser login isn't possible, such as in CI, send a personal access token of your own instead and no login happens:

claude mcp add unleash https://your-instance.getunleash.io/api/admin/mcp \
  --transport http \
  --header "Authorization: Bearer user:your-personal-access-token"

Codex takes the token from an environment variable named in its config.toml, as bearer_token_env_var under [mcp_servers.unleash].

Development

• Development setup: running tests and the dev server in Claude Code.
• Decisions: why the server works the way it does.