Integrate Unleash with Cursor for AI-powered feature flag management

The Unleash MCP server connects Cursor to your Unleash instance, enabling AI-assisted feature flag management. This page covers how to install and configure the server in Cursor. To learn what the server can do, see Unleash MCP server.

Cursor supports MCP across two interfaces:

Cursor IDE — The primary interface, an AI-first code editor with Agent mode
Cursor CLI — Terminal-based agent access via the agent command

Prerequisites

Before you begin, make sure you have the following:

Node.js 24 or later: The MCP server is distributed as an npm package
Cursor: IDE or CLI installed
An Unleash instance: Cloud or self-hosted, with API access enabled
A personal access token (PAT): With permissions to create and manage feature flags

Install the MCP server

The Unleash MCP server runs as a local stdio process. Configuration differs between the IDE and CLI, but both use the same npm package and credentials.

First, create a credentials file:

mkdir -p ~/.unleash
cat > ~/.unleash/mcp.env << 'EOF'
UNLEASH_BASE_URL=https://your-instance.getunleash.io
UNLEASH_PAT=your-personal-access-token
EOF
chmod 600 ~/.unleash/mcp.env

Variable	Description	Required
`UNLEASH_BASE_URL`	Your Unleash instance API URL.	Yes
`UNLEASH_PAT`	A personal access token with flag creation permissions.	Yes
`UNLEASH_MCP_SEND_FEEDBACK`	Set to `true` or `false` to opt in to or out of feedback reports without a consent prompt. With `false`, the assistant doesn’t see the `send_feedback` tool.	No

Now configure your preferred interface:

Cursor IDE

Cursor CLI

Requirements: Cursor installed.

You can add the Unleash MCP server with a one-click install from cursor.directory or by creating the configuration file manually.

One-click install

Create file manually

The Unleash MCP server is listed on cursor.directory.

Click Add to Cursor on the listing page, or open this link directly.

Cursor opens and pre-fills the MCP server configuration. The installer prompts you for your UNLEASH_BASE_URL and UNLEASH_PAT values.

The one-click flow writes credentials directly into .cursor/mcp.json. This is fine for personal use, but for team projects you should replace the inline values with an envFile reference so the configuration file is safe to commit. See the “Create file manually” tab for details.

Configuration scopes:

Location	Scope	Use case
`.cursor/mcp.json` (project root)	Project	Team-shared, version controlled
`~/.cursor/mcp.json`	Global	Personal settings across all projects

Both are merged; project takes precedence on conflict. For team collaboration, use the project-level file.

Cursor uses its own .cursor/mcp.json location with the "mcpServers" root key. This differs from VS Code’s .vscode/mcp.json with a "servers" root key. If you are migrating from VS Code, update the file location and root key.

Tools and workflows

Once the server is connected, Cursor can use every tool the Unleash MCP server exposes. To learn what the server can do and see step-by-step workflows, read Unleash MCP server. For the current list of tools, see the README on GitHub.

Feedback reports

The first time the assistant tries to send a feedback report, Cursor shows a consent prompt in the chat. The MCP server saves whether you opted in or out, so you see the prompt only once.

To opt in or out without the prompt, add UNLEASH_MCP_SEND_FEEDBACK=true or UNLEASH_MCP_SEND_FEEDBACK=false to your envFile, or set the variable in the env block of .cursor/mcp.json. To learn what a report contains, see What is recorded.

Enterprise governance

Cursor provides enterprise controls relevant to MCP server deployment.

MCP server trust management — Enterprise admins can whitelist or blocklist specific MCP servers at the organization level. Ensure the Unleash MCP server is on the whitelist.
Privacy mode — Enforces zero data retention with AI providers. Enabled by default for team members. Does not affect MCP server communication, which goes directly to your Unleash instance.
Agent sandbox — Enforceable org-wide on Enterprise plans. Controls what the agent can execute autonomously.
Audit logs — Track administrative actions including MCP-related operations.
SSO/SCIM — SAML/OIDC authentication and automated user provisioning.

For MCP server governance, commit .cursor/mcp.json to version control. This ensures all team members use the same MCP servers.

Use tool approval prompts for write operations like release, kill_switch, and manage_flag. Auto-run is appropriate for read-only operations like search, inspect, and evaluate.

Troubleshooting

MCP server not appearing in Cursor

Check .cursor/mcp.json for syntax errors
Verify the file is at the project root under .cursor/
Open Settings > Features > Model Context Protocol and toggle the server on
Restart Cursor after making changes
Check MCP logs via Output panel > “MCP Logs”

Environment variables not expanding

Cursor uses ${env:NAME} syntax (not ${NAME} or ${VAR})
Restart your terminal and IDE after modifying your shell profile
Verify variables are exported: echo $UNLEASH_BASE_URL
If using envFile, verify the file path is correct and the file exists

Authentication failed

Confirm your Unleash PAT is valid and has not expired
Check that the PAT has permissions to create and manage feature flags
Verify that UNLEASH_BASE_URL does not include /api at the end
Test directly: curl -H "Authorization: $UNLEASH_PAT" "$UNLEASH_BASE_URL/api/admin/projects"

Node.js not found

Local servers using npx require Node.js 24+. Verify with node --version. If Node.js is installed but not found by Cursor, check that the IDE inherits your shell PATH.

Tool approval prompts

By default, the agent requests approval before executing MCP tools. Configure auto-run in Settings or use ~/.cursor/permissions.json for granular control. In the CLI, use --approve-mcps.

CLI shows 'not loaded (needs approval)'

agent mcp list may show “not loaded (needs approval)” even after running agent mcp enable. This is expected. MCP servers are lazy-loaded and only start when an agent session begins. Start an interactive session with agent --approve-mcps to auto-approve, or approve the server when prompted during your first session. Once approved, subsequent sessions load the server automatically.

Cloud Agent MCP access

Cloud Agents access MCP servers configured for the team. Ensure the Unleash MCP server is configured at the team level and credentials are set in the Cloud Agent Secrets tab.

envFile vs env interpolation

Use envFile for simplicity. Use ${env:NAME} interpolation if you need per-variable control or mixing environment sources. Don’t use both for the same variable.

Feedback is disabled

send_feedback returns this message if you declined the consent prompt, if Cursor couldn’t show it, or if UNLEASH_MCP_SEND_FEEDBACK is set to false. To opt in, add UNLEASH_MCP_SEND_FEEDBACK=true to your envFile or to the env block of .cursor/mcp.json, then restart the server in Settings > Features > Model Context Protocol. To see the consent prompt again, delete feedback_consent.json from the configuration directory. Feedback settings don’t affect flag operations.