Integrate Unleash with OpenCode

The Unleash MCP server connects OpenCode to your Unleash instance, enabling AI-assisted feature flag management. You can evaluate code changes, create flags, generate wrapping code, manage rollouts, and clean up flags from within OpenCode’s terminal-first development environment.

OpenCode supports MCP across three interfaces:

• OpenCode TUI — The primary terminal-based interface with custom agents, skills, and commands
• OpenCode CLI — Non-interactive mode via opencode run for scripts and CI/CD
• Desktop app — GUI alternative available for macOS, Windows, and Linux

OpenCode is model-neutral, supporting 75+ LLM providers through Models.dev, including Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), and local models via Ollama. When developers can switch providers between sessions, governance cannot live in the model. It must live in the tools. Custom agents with fine-grained permission controls are the primary governance mechanism, ensuring consistent FeatureOps behavior regardless of which model writes the code.

Prerequisites

Before you begin, make sure you have the following:

• Node.js 18 or later: The MCP server is distributed as an npm package
• OpenCode: TUI, CLI, or desktop app 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. The same configuration works across all OpenCode interfaces (TUI, CLI, and desktop app).

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

$
# Unleash MCP credentials
$
if [ -f ~/.unleash/mcp.env ]; then
$
  source ~/.unleash/mcp.env
$
  export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
$
fi

1
{
2
  "mcp": {
3
    "unleash": {
4
      "type": "local",
5
      "command": ["npx", "-y", "@unleash/mcp@latest", "--log-level", "error"],
6
      "environment": {
7
        "UNLEASH_BASE_URL": "{env:UNLEASH_BASE_URL}",
8
        "UNLEASH_PAT": "{env:UNLEASH_PAT}",
9
        "UNLEASH_DEFAULT_PROJECT": "{env:UNLEASH_DEFAULT_PROJECT}"
10
      }
11
    }
12
  }
13
}

$
opencode mcp list

Tool namespacing: OpenCode prefixes MCP tool names with the server name. The Unleash tools appear as unleash_evaluate_change, unleash_create_flag, unleash_get_flag_state, and so on.

Configuration scopes:

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

Tool reference

The Unleash MCP server exposes several tools. The following table summarizes each tool and when to use it.

Workflows

The Unleash MCP server supports these core workflows: evaluate and wrap code in feature flags, discover and audit flags, manage rollouts across environments, and clean up after rollout. OpenCode adds a fifth workflow unique to its architecture: agent-guided flag evaluation.

Evaluate and wrap code in feature flags

Use this workflow when implementing a change that might affect production stability, such as a payment integration, authentication flow, or external API call.

Evaluate whether the Stripe payment integration should be behind a feature flag.
The change modifies the checkout service and handles credit card processing.

Create a release flag for the Stripe payment integration.

Wrap the Stripe checkout handler with the stripe-payment-integration flag.
This is a Node.js Express application.

1
const { isEnabled } = require('unleash-client');
2
3
app.post('/checkout', async (req, res) => {
4
  const context = { userId: req.user.id };
5
6
  if (isEnabled('stripe-payment-integration', context)) {
7
    // New Stripe payment flow
8
    const result = await stripeService.processPayment(req.body);
9
    return res.json(result);
10
  } else {
11
    // Existing payment flow
12
    const result = await legacyPaymentService.process(req.body);
13
    return res.json(result);
14
  }
15
});

Agent-guided flag evaluation

Use this workflow to automate flag evaluation using a custom FeatureOps agent with permission controls. The agent evaluates risk without the developer explicitly asking, and its behavior is identical regardless of which model is selected.

Manage rollouts across environments

Use this workflow to enable a flag in staging for testing while keeping it disabled in production.

What is the current state and rollout strategies for stripe-payment-integration?

Clean up after rollout

Use this workflow when a feature has been fully rolled out and the flag is no longer needed.

Clean up the stripe-payment-integration flag. The feature is fully rolled out.

The agent calls cleanup_flag and returns:

• All files and line numbers where the flag is used
• Which code path to preserve (the “enabled” branch)
• Suggestions for tests to run after removal

Review the list, remove the conditional branches, and delete the flag from Unleash.

Discover and audit flags

Use this workflow to take inventory of existing flags before creating new ones, or to run a periodic audit for cleanup candidates.

AGENTS.md templates

OpenCode uses AGENTS.md files for project-level instructions, similar to Cursor Rules or Claude Code’s CLAUDE.md. Store your FeatureOps policies in AGENTS.md so the agent considers feature flags automatically in every session.

For more details on project instructions, see the OpenCode rules documentation.

Standard AGENTS.md with FeatureOps policies

This file loads into every agent session. Use it for organization-wide flag standards.

1
# Project Instructions
2
3
## Feature Flag Conventions
4
5
When making changes to this codebase, follow these feature flag practices:
6
7
1. **Always evaluate risk** – Before implementing high-risk changes (payments,
8
   authentication, data migrations, external integrations), use the Unleash MCP
9
   server to evaluate whether a feature flag is needed.
10
11
2. **Naming conventions** – Use the format `{domain}-{feature}-{variant}`.
12
   Examples: `checkout-stripe-integration`, `auth-sso-google`, `api-rate-limiting`.
13
14
3. **Flag types**:
15
   - `release` – For gradual feature rollouts
16
   - `experiment` – For A/B tests and experiments
17
   - `operational` – For system behavior toggles
18
   - `kill-switch` – For emergency shutdowns
19
   - `permission` – For role-based access
20
21
4. **Prefer reuse** – Before creating a new flag, check if a similar flag already
22
   exists using the detect_flag tool.
23
24
5. **Clean up after rollout** – Once a feature is fully released (100% rollout for
25
   2+ weeks), use cleanup_flag to remove dead code.
26
27
## Unleash MCP Server
28
29
This project uses the Unleash MCP server for feature flag management. Configuration
30
is in `opencode.json`. Credentials are sourced from environment variables.
31
32
Available tools: evaluate_change, detect_flag, create_flag, wrap_change,
33
list_projects, list_flags, get_flag_state, set_flag_rollout,
34
toggle_flag_environment, remove_flag_strategy, cleanup_flag.

Domain-specific instructions via opencode.json

Create additional instruction files for high-risk domains and load them via the instructions field in opencode.json. This field supports glob patterns and remote URLs.

1
{
2
  "instructions": ["AGENTS.md", "docs/featureops-policy.md", "docs/domain-policies/*.md"],
3
  "mcp": {
4
    "unleash": {
5
      "type": "local",
6
      "command": ["npx", "-y", "@unleash/mcp@latest", "--log-level", "error"],
7
      "environment": {
8
        "UNLEASH_BASE_URL": "{env:UNLEASH_BASE_URL}",
9
        "UNLEASH_PAT": "{env:UNLEASH_PAT}",
10
        "UNLEASH_DEFAULT_PROJECT": "{env:UNLEASH_DEFAULT_PROJECT}"
11
      }
12
    }
13
  }
14
}

1
# Payments Domain — Feature Flag Policy
2
3
All changes in the payments domain require feature flags. No exceptions.
4
5
- Use `kill-switch` type for external payment provider integrations
6
  (Stripe, PayPal, etc.)
7
- Use `release` type for internal payment logic changes
8
- Naming: `payments-{feature}-{variant}`
9
  (e.g., `payments-stripe-checkout`, `payments-refund-v2`)
10
- Always include a fallback path for external provider calls
11
- Evaluate risk with evaluate_change before writing implementation code

Custom agent definitions

Custom agents are OpenCode’s primary governance mechanism. Each agent has a mode, a system prompt, and fine-grained permission controls that gate what the agent can do. Permissions support three levels per tool: ask (prompt for approval), allow (execute without prompting), and deny (block entirely).

For more details on agents, see the OpenCode agents documentation.

Agents can be defined in two formats: JSON in opencode.json or as markdown files in .opencode/agents/.

FeatureOps agent

A primary agent with a custom prompt that always evaluates changes for feature flags. Edit operations require approval; destructive bash commands are blocked.

1
{
2
  "agent": {
3
    "featureops": {
4
      "description": "Feature flag management with Unleash governance policies",
5
      "mode": "primary",
6
      "prompt": "{file:.opencode/agents/featureops-prompt.md}",
7
      "permission": {
8
        "read": "allow",
9
        "edit": "ask",
10
        "bash": {
11
          "*": "deny",
12
          "npx @unleash/mcp*": "allow",
13
          "npm test*": "allow",
14
          "git status": "allow",
15
          "git diff*": "allow"
16
        },
17
        "glob": "allow",
18
        "grep": "allow",
19
        "skill": "allow"
20
      }
21
    }
22
  }
23
}

1
You are a FeatureOps agent. Your job is to evaluate code changes for risk and
2
manage feature flags using the Unleash MCP server.
3
4
## Workflow
5
6
1. When the developer describes a change, always call evaluate_change first
7
2. If a flag is needed, call detect_flag to check for duplicates
8
3. Only create a new flag if no suitable existing flag is found
9
4. Use wrap_change to generate framework-specific guard code
10
5. Suggest a rollout strategy based on the change's risk level
11
12
## Naming Convention
13
14
Use the format {domain}-{feature}-{variant}. Examples:
15
- checkout-stripe-integration
16
- auth-sso-google
17
- api-rate-limiting
18
19
## Flag Types
20
21
- release: Gradual feature rollouts
22
- experiment: A/B tests
23
- operational: System behavior toggles
24
- kill-switch: Emergency shutdowns
25
- permission: Role-based access

Flag reviewer agent

A read-only subagent that evaluates code changes for feature flag compliance without creating or modifying anything.

1
---
2
description: Reviews code changes for feature flag compliance
3
mode: subagent
4
temperature: 0.1
5
permission:
6
  read: allow
7
  edit: deny
8
  bash: deny
9
  glob: allow
10
  grep: allow
11
---
12
You are a feature flag reviewer. Analyze code changes and determine:
13
14
1. Whether the changes should be behind a feature flag (use evaluate_change)
15
2. Whether existing flags are being used correctly (use get_flag_state)
16
3. Whether any flags should be cleaned up (use cleanup_flag for analysis only)
17
18
Do NOT create or modify flags. Report findings and recommendations.

Skill and command definitions

Skills and commands package reusable workflows and common operations. Skills define multi-step processes that agents invoke automatically. Commands define prompt templates that developers invoke with /command-name in the TUI.

evaluate-and-flag skill

1
---
2
name: evaluate-and-flag
3
description: Evaluate whether current code changes need a feature flag, then
4
  create and wrap the flag if needed. Handles duplicate detection, naming
5
  conventions, and framework-specific wrapping.
6
---
7
8
## What I do
9
10
Evaluate the current code changes for risk and create a feature flag if needed.
11
12
## Steps
13
14
1. **Evaluate risk** – Call evaluate_change with a description of the current
15
   changes. Include the component, service, and risk factors.
16
17
2. **Check for duplicates** – If a flag is needed, call detect_flag to check for
18
   existing similar flags. Present matches to the developer.
19
20
3. **Create the flag** – If no suitable flag exists, call create_flag with:
21
   - Name following {domain}-{feature}-{variant} convention
22
   - Appropriate type (release, experiment, operational, kill-switch, permission)
23
   - Clear description
24
25
4. **Wrap the code** – Call wrap_change to generate framework-specific guard code.
26
   Insert the code at the appropriate location.
27
28
5. **Suggest rollout** – Recommend a rollout strategy:
29
   - Low risk: Enable immediately in staging, 50% in production
30
   - Medium risk: 10% then 50% then 100% over 48 hours
31
   - High risk: 10% then 25% then 50% then 100% over one week with error monitoring
32
33
## When to skip
34
35
- CSS-only changes
36
- Documentation updates
37
- Test file changes
38
- Dependency version bumps (unless major versions)

cleanup-flag skill

1
---
2
name: cleanup-flag
3
description: Safely remove a feature flag after successful rollout. Handles code
4
  removal, test validation, and cleanup recommendations.
5
---
6
7
## What I do
8
9
Remove a feature flag and its associated conditional code after a feature has
10
been fully rolled out.
11
12
## Steps
13
14
1. **Verify rollout status** – Call get_flag_state to confirm the flag is at
15
   100% rollout and has been stable.
16
17
2. **Get cleanup instructions** – Call cleanup_flag to get:
18
   - File locations where the flag is used
19
   - Which code path to preserve (usually "enabled")
20
   - Tests to run after cleanup
21
22
3. **Remove conditional code** – Remove the feature flag check, keeping only
23
   the enabled code path. Remove unused imports and dead code.
24
25
4. **Run tests** – Execute the project's test suite to verify nothing breaks.
26
27
5. **Recommend flag deletion** – After code changes are merged, recommend
28
   deleting the flag from Unleash via the Admin UI or API.
29
30
## Safety checks
31
32
- Confirm all code is committed before making changes
33
- Create a snapshot before cleanup
34
- Run tests after cleanup
35
- Do not delete the flag from Unleash until code changes are merged

evaluate-flag command

1
---
2
description: Evaluate whether changes need a feature flag
3
agent: featureops
4
---
5
Evaluate whether the following changes should be behind a feature flag using
6
the Unleash MCP server.
7
8
Focus on: $ARGUMENTS
9
10
Steps:
11
1. Call evaluate_change with the description
12
2. If a flag is needed, call detect_flag to check for duplicates
13
3. If no suitable flag exists, suggest a name and type
14
4. Ask for approval before creating the flag

Usage: /evaluate-flag Stripe payment integration in the checkout service

Team distribution

Commit the .opencode/ directory to version control so the entire team shares the same agents, skills, and commands:

.opencode/
├── agents/
│   ├── featureops.md
│   ├── featureops-prompt.md
│   └── flag-reviewer.md
├── skills/
│   ├── evaluate-and-flag/
│   │   └── SKILL.md
│   └── cleanup-flag/
│       └── SKILL.md
└── commands/
    ├── evaluate-flag.md
    └── cleanup-flag.md

Prompt patterns

The following prompt patterns help you use the MCP tools effectively.

Evaluate whether the [description of change] should be behind a feature flag.
The change modifies [component/service].

Before creating a new flag for [feature], check if a similar flag already exists
and suggest reusing it if appropriate.

Enable [flagName] in the staging environment.

What is the current state and rollout strategies for [flagName]?

Clean up the [flagName] flag now that the feature has fully shipped.

Clean up the [flagName] flag after the A/B testing experiment, only keep [variant].

List all feature flags in the [projectId] project and identify any that should be cleaned up.

Run a flag audit: list all projects, then check for flags at 100% rollout for more than 14 days.

$
# Non-interactive evaluation
$
opencode run "Evaluate whether the Stripe integration should be behind a feature flag"
$
$
# With specific agent and model
$
opencode run --agent featureops --model anthropic/claude-sonnet-4-20250514 \
>
  "Evaluate the Stripe payment integration for feature flagging"
$
$
# Batch processing with the attach pattern
$
opencode serve &
$
opencode run --attach http://localhost:4096 "Evaluate changes in src/payments/"
$
opencode run --attach http://localhost:4096 "Evaluate changes in src/auth/"
$
$
# CI/CD with GitHub Actions
$
opencode github run --event '{"action":"opened","pull_request":{...}}' \
>
  --github-token "$GITHUB_TOKEN"

Enterprise governance

OpenCode Enterprise provides controls relevant to MCP server deployment in organizations.

• SSO integration — Central config integrates with your organization’s SSO provider. Enables credential access for internal AI gateways through existing identity systems. No separate OpenCode accounts needed.
• Private AI gateway — Restrict all AI provider access to internal infrastructure. Disable all external providers to ensure requests route through approved channels. Combined with the Unleash MCP server (which connects to your own Unleash instance), the entire stack operates within your network.
• Managed configuration — Non-overridable policies deployed via MDM on macOS (.mobileconfig profiles), /etc/opencode/ on Linux, and %ProgramData%\opencode on Windows. Managed config has the highest precedence in the configuration hierarchy, so individual developers cannot override these settings.
• Agent permission restrictions — Enforce FeatureOps agent definitions and permission policies via managed config. A managed FeatureOps agent with "edit": "ask" ensures every file change requires approval, regardless of the developer’s local configuration.
• Disabled providers list — Restrict which LLM providers are available to developers. Useful for organizations that need to route all AI traffic through approved gateways.

For MCP server governance, commit opencode.json and the .opencode/ directory to version control. This ensures all team members use the same MCP servers, agents, and skills with the same permission policies.

Troubleshooting

Best practices

Follow these guidelines for effective feature flag management with OpenCode.

Related resources

• Unleash MCP server on GitHub
• OpenCode homepage
• OpenCode documentation
• OpenCode MCP configuration
• OpenCode agents documentation
• Impact Metrics
• Unleash architecture overview