Building a FeatureOps Agent in OpenCode with the Unleash MCP server

The first post in this series covered why model-neutral governance matters for feature flags. When developers can switch between Claude, GPT, Gemini, or a local model between sessions, the governance layer cannot depend on the model’s behavior. It has to live in the tools.

This post is the hands-on follow-up. We will connect the Unleash MCP server to OpenCode, encode policies in AGENTS.md, build a custom FeatureOps agent with permission controls, add reusable skills and commands, and run batch operations from the CLI. Each step builds on the previous one. By the end, you will have a governance setup that works identically regardless of which model your developers choose.

What you need before starting

The Unleash MCP server runs as a local process that communicates with OpenCode via the Model Context Protocol. You will need:

• Node.js 18+ for running the MCP server via npx
• OpenCode Terminal
• An Unleash instance with API access (cloud or self-hosted)
• A personal access token (PAT) with permissions to create and manage feature flags

Step 1: Connect the MCP server

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
UNLEASH_DEFAULT_PROJECT=default
EOF
chmod 600 ~/.unleash/mcp.env

Source it from your shell profile (~/.zshrc or ~/.bashrc):

if [ -f ~/.unleash/mcp.env ]; then
  source ~/.unleash/mcp.env
  export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
fi

Restart your terminal, then create opencode.json at your project root:

{
  "mcp": {
    "unleash": {
      "type": "local",
      "command": ["npx", "-y", "@unleash/mcp@latest", "--log-level", "error"],
      "environment": {
        "UNLEASH_BASE_URL": "{env:UNLEASH_BASE_URL}",
        "UNLEASH_PAT": "{env:UNLEASH_PAT}",
        "UNLEASH_DEFAULT_PROJECT": "{env:UNLEASH_DEFAULT_PROJECT}"
      }
    }
  }
}

Run opencode mcp list to confirm the server is connected. You should see unleash: connected.

This file contains no credentials. Commit it to version control so every developer on the team gets the same MCP server configuration.

Your first workflow: evaluate, create, wrap

Open the terminal interface and tell the agent what you are working on:

Evaluate whether the Stripe payment integration should be behind a feature flag. The change modifies the checkout service.

The agent calls evaluate_change with your description. For a payment integration, it recommends a flag. It then calls detect_flag to check for duplicates. If none are found, it proceeds to create_flag with a name like checkout-stripe-integration, and finally calls wrap_change to produce framework-specific guard code:

if (unleash.isEnabled('checkout-stripe-integration', context)) {
  return stripeService.processPayment(request);
} else {
  return legacyPaymentService.process(request);
}

The flag is created in Unleash, disabled by default. You can test in staging, roll out gradually, and disable instantly if something goes wrong.

This works, but it relies on the developer knowing to ask. The next steps make conventions automatic.

Step 2: Encode policies in AGENTS.md

OpenCode reads an AGENTS.md file at the project root and applies its guidance automatically. Create one with your feature flag conventions:

# Project Instructions

## Feature Flag Conventions

When making changes to this codebase:

1. **Always evaluate risk** before implementing changes to payments,
   authentication, data migrations, or external integrations.
   Use the evaluate_change tool.

2. **Naming** — Use the format `{domain}-{feature}-{variant}`.
   Examples: `checkout-stripe-integration`, `auth-sso-google`.

3. **Flag types**:
   - `release` for gradual feature rollouts
   - `experiment` for A/B tests
   - `kill-switch` for emergency shutdowns

4. **Prefer reuse** — Check for existing flags with detect_flag before creating.

5. **Clean up after rollout** — Flags at 100% for 2+ weeks should be cleaned up.

Now when a developer asks OpenCode to add Stripe payment processing, the agent considers whether a feature flag is needed without being explicitly asked. The model reads AGENTS.md and follows its guidance. Because the file is committed to version control, everyone on the team gets the same policies.

For larger codebases, load domain-specific instruction files via opencode.json:

{
  "instructions": ["AGENTS.md", "docs/domain-policies/*.md"]
}

Each file in docs/domain-policies/ can define domain-specific flag requirements such as “all changes in the payments domain require kill-switch flags“. OpenCode loads all matched files and merges the instructions.

Step 3: Build a FeatureOps agent with permission controls

AGENTS.md tells the agent what to do. A custom agent controls what the agent is allowed to do: this is OpenCode’s primary governance mechanism.

Each custom agent has a mode, a system prompt, and fine-grained permissions. Permissions support three levels per capability: ask (prompt for approval), allow (execute without prompting), and deny (block entirely). Bash permissions support glob patterns, so you can allow “npm test*” while denying everything else.

Create .opencode/agents/featureops.md:

---
description: Feature flag management with Unleash governance policies
mode: primary
permission:
  read: allow
  edit: ask
  bash:
    "*": deny
    "npm test*": allow
    "git status": allow
    "git diff*": allow
  glob: allow
  grep: allow
  skill: allow
---
You are a FeatureOps agent. Your job is to evaluate code changes for risk
and manage feature flags using the Unleash MCP server.

## Workflow

1. When the developer describes a change, always call evaluate_change first
2. If a flag is needed, call detect_flag to check for duplicates
3. Only create a new flag if no suitable existing flag is found
4. Use wrap_change to generate framework-specific guard code
5. Suggest a rollout strategy based on the change's risk level

## Naming Convention

Use the format {domain}-{feature}-{variant}. Examples:
- checkout-stripe-integration
- auth-sso-google
- api-rate-limiting

Press Tab in the TUI to switch to the FeatureOps agent. Now the agent always evaluates risk before creating flags, and the permission model ensures every file edit requires your approval. Destructive bash commands are blocked entirely.

The key insight: this agent works identically whether the developer selects Claude, GPT, Gemini, or a local model via Ollama. The model provides the reasoning. The agent definition provides the guardrails. The MCP server provides the tools. Three independent layers, none of which depends on a specific model.

For read-only auditing, add a second agent:

---
description: Reviews code changes for feature flag compliance
mode: subagent
temperature: 0.1
permission:
  read: allow
  edit: deny
  bash: deny
  glob: allow
  grep: allow
---
You are a feature flag reviewer. Analyze code changes and report:

1. Whether changes should be behind a feature flag (use evaluate_change)
2. Whether existing flags are used correctly (use get_flag_state)
3. Whether any flags should be cleaned up (use cleanup_flag for analysis only)

Do NOT create or modify flags. Report findings and recommendations.

Save as .opencode/agents/flag-reviewer.md. This agent cannot edit files or run commands. It can only read, analyze, and recommend.

Step 4: Add skills and commands

Skills define reusable multi-step workflows. Commands package common prompts as shortcuts. Both complement the MCP server: the server provides the tools, while skills and commands orchestrate when and how those tools are used.

Create .opencode/skills/evaluate-and-flag/SKILL.md:

---
name: evaluate-and-flag
description: Evaluate whether current code changes need a feature flag,
  then create and wrap the flag if needed.
---

## Steps

1. **Evaluate risk** — Call evaluate_change with a description of the changes
2. **Check for duplicates** — If a flag is needed, call detect_flag
3. **Create the flag** — If no duplicate exists, call create_flag with
   {domain}-{feature}-{variant} naming
4. **Wrap the code** — Call wrap_change for framework-specific guard code
5. **Suggest rollout** — Recommend a strategy based on risk level

The agent discovers skills automatically when the context is relevant, or you can reference it directly.

For quick one-line operations, create commands in .opencode/commands/. For example, here’s a flag audit command:

---
description: Audit all feature flags for cleanup opportunities
---
Run a feature flag audit:

1. Use list_projects to enumerate available projects
2. Use list_flags to retrieve active flags in each project
3. Use list_flags with archived=true for archived flags
4. Cross-reference each flag against code references
5. Use get_flag_state for flags that need deeper inspection
6. Generate a prioritized cleanup report

Save as .opencode/commands/flag-audit.md. Now /flag-audit in the TUI runs a complete inventory and cleanup analysis.

Step 5: CLI workflows for automation

Everything above works in the interactive TUI. For batch operations and CI/CD, use the CLI.

Non-interactive evaluation:

opencode run "Evaluate whether the changes in this branch should be feature flagged"

With agent and model selection:

opencode run \
    --agent featureops \
    --model anthropic/claude-sonnet-4-20250514 \
    "Evaluate the Stripe payment integration for feature flagging"

Batch processing with the attach pattern. Start the server once to avoid cold-booting MCP servers for each invocation:

opencode serve &
opencode run --attach http://localhost:4096 "Evaluate changes in src/payments/"
opencode run --attach http://localhost:4096 "Evaluate changes in src/auth/"
opencode run --attach http://localhost:4096 "Run flag cleanup audit"

GitHub Actions integration:

opencode github run \
    --event '{"action":"opened","pull_request":{...}}' \
    --github-token "$GITHUB_TOKEN"

What you built

Five layers, each building on the last:

1. The Unleash MCP server gives the agent the tools to create and manage feature flags
2. AGENTS.md encodes your team’s conventions so any model follows them
3. A FeatureOps agent adds permission controls so risky operations require approval
4. Skills and commands package workflows into repeatable, shareable sequences
5. CLI workflows extend everything to batch operations and CI/CD

The entire setup lives in three places: opencode.json (MCP config), AGENTS.md (policies), and .opencode/ (agents, skills, commands). All committed to version control. No marketplace, no vendor lock-in. A new developer clones the repo and gets the full governance setup from their first session, regardless of which model they choose.

Start with Step 1 and a few manual workflows. Add AGENTS.md when you see naming drift. Build the FeatureOps agent when you want permission-controlled governance. Add skills when you want repeatable workflows. Each step is valuable on its own.

For the full configuration reference, including additional agent templates and troubleshooting guides, see our OpenCode integration documentation and the Unleash MCP server repository.