Bucketeer MCP Server

How to use

To interact with Bucketeer feature flags via MCP, use a client that speaks the MCP protocol and point it at your Bucketeer MCP endpoint. You can run the MCP server locally with an easy npx command, or install and run it directly from your environment. The server supports the following core operations: listFeatureFlags, createFeatureFlag, getFeatureFlag, updateFeatureFlag, and archiveFeatureFlag.

Set up your client with the appropriate environment details and API key. You will typically pass your Bucketeer API host, API key, and the environment ID to the MCP client so requests are authenticated and scoped to the correct environment.

If you start from a local installation, ensure you have Node.js 18 or higher and a Bucketeer instance with API access. Use the provided commands to run the MCP server, then configure your MCP client to connect to it using the credentials and environment information you defined.

The server exposes a precise set of tools for feature flag management. You can filter and paginate the list of flags, create new flags with multiple variations, retrieve specific flags, update flags (with an audit-friendly required comment), and archive flags to mark them inactive. When a flag is archived, the default value defined in your code is used for all users unless you unarchive and adjust configurations.

How to install

Prerequisites you need before installing the Bucketeer MCP Server:

- Node.js 18 or higher

- A Bucketeer instance with API access

- An API key with appropriate permissions (READ, WRITE, or ADMIN)

Choose one of the following installation methods to run the MCP server.

# Run using npx (Recommended)
npx @bucketeer/mcp

Using npx (Recommended)

The easiest way to run Bucketeer MCP Server is with npx, which requires no local installation.

npx @bucketeer/mcp

Using Local Installation

If you prefer to install locally, follow these steps to clone, install, build, and run the server.

# 1. Clone the repository
git clone https://github.com/bucketeer-io/bucketeer-mcp.git
cd bucketeer-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Start the MCP server (see below for start commands)
npm start

MCP Client Configuration

Configure your MCP client to connect to Bucketeer MCP. You can use either the npx-based approach or a local installation. The following configurations illustrate how to specify the MCP server in your client settings.

{
  "mcpServers": {
    "bucketeer": {
      "command": "npx",
      "args": ["@bucketeer/mcp"],
      "env": {
        "BUCKETEER_HOST": "api.bucketeer.io",
        "BUCKETEER_API_KEY": "your-api-key",
        "BUCKETEER_ENVIRONMENT_ID": "your-environment-id"
      }
    }
  }
}

Using Local Installation

If you installed Bucketeer MCP Server locally, configure the client to run against the local runtime.

{
  "mcpServers": {
    "bucketeer": {
      "command": "node",
      "args": ["/path/to/bucketeer-mcp/dist/index.js"],
      "env": {
        "BUCKETEER_HOST": "api.bucketeer.io",
        "BUCKETEER_API_KEY": "your-api-key",
        "BUCKETEER_ENVIRONMENT_ID": "your-environment-id"
      }
    }
  }
}

listFeatureFlags

List all feature flags in the specified environment with optional filtering, pagination, and search.

createFeatureFlag

Create a new feature flag with a set of variations, tags, and default mappings for on/off states.

getFeatureFlag

Retrieve a specific feature flag by its ID, optionally for a particular environment and version.

updateFeatureFlag

Update an existing feature flag with changes to name, description, tags, enabled state, or archived status. Requires a comment for audit trail.

archiveFeatureFlag

Archive a feature flag to deactivate it and use the code-defined default value for all users.