Overview

This MCP (Model Context Protocol) server connects LLM-based applications to Unleash feature toggles. It provides a small HTTP service that accepts model/context-aware requests from language-model orchestrators and returns feature flag evaluations from an Unleash backend. By acting as a bridge between model context and Unleash, the server helps teams centralize flag logic and apply feature controls consistently across multiple models and services.

The server is useful when you want conditional behavior in prompts, runtime routing between model generations, or gradual rollouts that depend on model identity, user attributes, or session context. Instead of embedding toggle logic inside models or multiple services, you query the MCP server to get deterministic flag states tailored to the current model and contextual attributes.

Features

Model-aware feature flag evaluation against an Unleash instance
Simple HTTP endpoints adhering to an MCP-style request/response pattern
Context-driven evaluations (model id, user id, session, attributes)
Supports Unleash API key authentication and environments
Docker-friendly and runnable as a lightweight microservice
Minimal dependencies for easy integration into LLM toolchains

Installation / Configuration

Prerequisites:

Unleash server URL and a client API key with read access
Node.js (if running locally) or Docker

Clone and run locally (Node.js)

git clone https://github.com/cuongtl1992/unleash-mcp.git
cd unleash-mcp
npm install
# set environment variables then start
export UNLEASH_URL="https://unleash.example.com"
export UNLEASH_API_KEY="your-unleash-api-key"
export PORT=8080
npm start

Run with Docker

# build
docker build -t unleash-mcp .

# run
docker run -e UNLEASH_URL="https://unleash.example.com" \
           -e UNLEASH_API_KEY="your-unleash-api-key" \
           -e PORT=8080 \
           -p 8080:8080 \
           unleash-mcp

Common environment variables

Variable	Description	Example
UNLEASH_URL	Base URL of your Unleash server	https://unleash.example.com
UNLEASH_API_KEY	API key with permission to read feature toggles	abc123
PORT	HTTP port for the MCP server	8080
UNLEASH_APP_NAME	Optional application name used when contacting Unleash	unleash-mcp

Configuration file (optional)

{
  "unleash": {
    "url": "https://unleash.example.com",
    "apiKey": "your-unleash-api-key",
    "appName": "unleash-mcp"
  },
  "server": {
    "port": 8080
  }
}

Available Tools / Resources

GitHub repository (source and examples): https://github.com/cuongtl1992/unleash-mcp
Unleash documentation for toggles and strategies: https://www.unleash-hosted.com/docs
Example Dockerfile and sample config in the repo
Example cURL snippets and JSON schemas for request/response shapes included in the repository

Example API overview (typical endpoints)

GET /mcp/v1/feature/:name?model=…&user=… — evaluate a single flag for provided context
POST /mcp/v1/features — bulk evaluation by sending a JSON payload with model and attributes
GET /health — liveness/readiness probe

(Actual endpoints and shapes are provided in the repository README and example clients.)

Use Cases

Model-specific feature gating
- Problem: You want a new response formatting feature enabled only for high-capacity models.
- Solution: In your prompt pipeline, call the MCP server with model=gpt-4.1 to check flag “response.rich_formatting”. If enabled, include richer output instructions in the prompt.
Example curl:
```
curl "http://localhost:8080/mcp/v1/feature/response.rich_formatting?model=gpt-4.1&user=user-123"
```
Example JSON response:
```
{
  "name": "response.rich_formatting",
  "enabled": true,
  "variant": "on"
}
```
Per-user experiments across models
- Problem: Run an A/B test for a feature that involves multiple models and needs consistent exposure per user.
- Solution: Use the MCP server to evaluate the flag with user id and session attributes so Unleash applies the same variant across requests and models.
Canary or staged rollouts
- Problem: Gradually enable a model-behavior change only for a percentage of traffic or specific regions.
- Solution: Configure Unleash strategies and evaluate them through the MCP server using model and region attributes provided by the orchestration layer.
Centralized policy enforcement
- Problem: Multiple services and model components need consistent checks (e.g., safety toggles, telemetry).
- Solution: Route all feature checks to one MCP server backed by Unleash to maintain a single source of truth.

Getting help

See the repository README for API contract examples, sample clients, and contribution instructions. For Unleash-specific strategy configuration and advanced behaviors, consult Unleash documentation or reach out in the Unleash community channels.

MCP Server for Unleash Feature Toggles