Unleash MCP Server

A Model Context Protocol server for managing Unleash feature flags.

Key Features

• ✅ Multiple Instance Support - Connect to multiple Unleash instances (prod, staging, dev)
• 🏗️ Multi-Environment Management - Handle different environments within each instance
• 🚀 Complete Feature Flag Operations - Create, toggle, archive, and monitor feature flags
• 🌍 Environment Management - List and understand your deployment environments

Quick Setup

Step 1: Configure Environment Variables

Choose one of the following options:

Option 1: Interactive Setup (Recommended)

First, install the package globally:

npm install -g @mcp-toolbox/unleash-server

Then run the setup wizard:

unleash-server-setup

This will guide you through connecting to your Unleash instances with a friendly interactive wizard.

Option 2: Config File

Create ~/.config/mcp-toolbox/unleash-toolbox.json:

{
  "instances": [
    {
      "name": "production",
      "url": "https://your-unleash.com",
      "token": "your-admin-token",
      "project": "default"
    }
  ]
}

Option 3: Environment Variables

# Single instance
export UNLEASH_URL=https://your-unleash.com
export UNLEASH_TOKEN=your-admin-token

# Multiple instances
export UNLEASH_INSTANCES='[
  {
    "name": "production",
    "url": "https://your-unleash.com",
    "token": "your-admin-token",
    "project": "default"
  },
  {
    "name": "staging",
    "url": "https://staging-unleash.com", 
    "token": "staging-token",
    "project": "default"
  }
]'

Step 2: Add to Your Agent

opencode

{
  "mcpServers": {
    "unleash": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@mcp-toolbox/unleash-server@latest"],
      "enabled": true
    }
  }
}

Claude Desktop, Cursor, Windsurf, and other agents

{
  "mcpServers": {
    "unleash": {
      "command": ["npx", "-y", "@mcp-toolbox/unleash-server@latest"]
    }
  }
}

API Token Requirements

You need Admin API tokens (or Service Account tokens) with the following permissions:

• Create feature flags
• Update feature flags
• Archive feature flags
• Read feature flags
• Manage environments

Interactive Setup Walkthrough

When you run bun run setup, you'll be guided through:

1. 🔍 Configuration Detection - Checks for existing config
2. 📋 Instance Setup - Add your Unleash instances one by one
3. 🔗 Connection Testing - Validates URLs and API tokens
4. 📊 Discovery - Shows available projects and environments
5. 💾 Save Options - Choose how to save your configuration
6. 📋 Next Steps - Get your Claude Desktop config

The setup wizard will:

• ✅ Test connections in real-time
• ✅ Validate API tokens and permissions
• ✅ Discover projects and environments
• ✅ Generate Claude Desktop configuration
• ✅ Provide helpful error messages and recovery options

Available Tools

Instance & Environment Management

• list_instances - Shows all configured Unleash servers
• list_environments - Shows all available environments in an instance

Feature Flag Management

• list_features - Shows all feature flags with their status in a specific environment
• list_all_features - Shows feature flags with global status (not environment-specific)
• get_feature_status - Gets detailed information about a specific feature flag
• create_feature - Creates a new feature flag (automatically disabled in all environments)
• toggle_feature - Enables or disables a feature flag in a specific environment ⚠️ Requires confirmation
• archive_feature - Archives a feature flag when no longer needed ⚠️ Requires confirmation

Strategy Management

• add_feature_strategy - Add a strategy to a feature flag in a specific environment
• update_feature_strategy - Update a strategy on a feature flag in a specific environment ⚠️ Requires confirmation
• delete_feature_strategy - Delete a strategy from a feature flag in a specific environment ⚠️ Requires confirmation

Tag Management

• list_tag_types - List all available tag types in an instance
• create_tag_type - Create a new tag type
• delete_tag_type - Delete a tag type ⚠️ Requires confirmation
• add_feature_tag - Add a tag to a feature flag
• get_feature_tags - Get all tags for a feature flag
• delete_tag - Delete a tag from all features ⚠️ Requires confirmation

Safety Features

Two-Step Confirmation for Destructive Actions

To prevent accidental changes to your feature flags, the following operations require explicit confirmation:

• Toggling feature flags (enable/disable)
• Archiving feature flags
• Updating strategies
• Deleting strategies
• Deleting tags and tag types

How It Works

1. First Call - When you attempt a destructive action without confirmation:

   ⚠️  CONFIRMATION REQUIRED
      
   You are about to DISABLE a feature flag:
   - Feature: new-checkout
   - Environment: production
   - Instance: production
   - Project: default
      
   This will deactivate this feature for users in the production environment.
      
   To proceed, call this tool again with confirmed=true

2. Second Call - To confirm, call the same tool again with confirmed=true:

   • The action will be executed immediately
   • No additional confirmation needed

This two-step process ensures you always have a chance to review critical changes before they're applied.

API Reference

This server uses the Unleash Admin API.