Integrate Unleash with OpenAI Codex

The Unleash MCP server connects OpenAI Codex 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 Codex.

Codex supports MCP across two local interfaces that share the same configuration file:

• Codex CLI — The open-source terminal agent, installed with npm or Homebrew
• Codex IDE extension — The editor integration for VS Code and compatible editors

Codex governs the agent while it writes code, through an operating-system sandbox and an approval prompt that appears before each action, including every MCP tool call. Feature flags govern the code after it ships, through progressive rollout and instant rollback. The two work together: Codex keeps a human in the loop at authoring time, and Unleash keeps the release under control at runtime.

Prerequisites

Before you begin, make sure you have the following:

• Node.js 18 or later: The MCP server is distributed as an npm package
• Codex: The CLI or the IDE extension, installed
• A signed-in Codex session: Run codex login and sign in with your ChatGPT account, or configure an API key
• 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

Codex stores its configuration in ~/.codex/config.toml. The CLI and the IDE extension read the same file, so you configure the server once.

$
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

$
codex mcp add unleash \
>
  --env UNLEASH_BASE_URL="$UNLEASH_BASE_URL" \
>
  --env UNLEASH_PAT="$UNLEASH_PAT" \
>
  --env UNLEASH_DEFAULT_PROJECT="${UNLEASH_DEFAULT_PROJECT:-default}" \
>
  -- npx -y @unleash/mcp@latest --log-level error

1
[mcp_servers.unleash]
2
command = "npx"
3
args = ["-y", "@unleash/mcp@latest", "--log-level", "error"]
4
env = { UNLEASH_BASE_URL = "https://your-instance.getunleash.io", UNLEASH_PAT = "your-personal-access-token", UNLEASH_DEFAULT_PROJECT = "default" }

1
[mcp_servers.unleash]
2
command = "npx"
3
args = ["-y", "@unleash/mcp@latest", "--log-level", "error"]
4
5
[mcp_servers.unleash.env]
6
UNLEASH_BASE_URL = "https://your-instance.getunleash.io"
7
UNLEASH_PAT = "your-personal-access-token"
8
UNLEASH_DEFAULT_PROJECT = "default"

$
codex mcp list      # shows: unleash
$
codex mcp get unleash

Approval and sandbox model

Codex enforces an authoring-time boundary through two independent controls. Understanding them explains how MCP tool calls behave.

The approval prompt

By default, Codex asks before it runs a tool. When the agent calls an Unleash tool, it shows you the tool name and its arguments, then waits:

Allow the unleash MCP server to run tool "list_projects"?
  limit: 100
  offset: 0
  order: asc
  › 1. Allow                   Run the tool and continue.
    2. Allow for this session  Run the tool and remember this choice for this session.
    3. Always allow            Run the tool and remember this choice for future tool calls.
    4. Cancel                  Cancel this tool call

For a write like create_flag or toggle_flag_environment, you see the flag name and target environment before anything happens. This is a genuine control, so keep the prompt on for writes and reserve “Always allow” for read-only tools.

The sandbox

Codex runs commands inside an operating-system sandbox: read-only, workspace-write (the default for interactive work, with network off), or danger-full-access. These map to the UI presets Read Only, Auto, and Full Access. The Unleash MCP server reaches your instance normally under the default workspace-write sandbox, so you do not need to weaken the sandbox to manage flags.

Tool reference

The Unleash MCP server exposes the following tools.

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.

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
});

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.

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.

AGENTS.md templates

Codex reads AGENTS.md files for project instructions. Store your FeatureOps policies in AGENTS.md so the agent considers feature flags automatically in every session.

Codex merges AGENTS.md files from a global ~/.codex/AGENTS.md down through your repository, with files closer to the working directory taking precedence. Put universal conventions at the repository root and stricter policies in subdirectories.

Repository root: universal conventions

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

Subdirectory: domain-specific policy

Place this file in a high-risk directory (for example payments/AGENTS.md). Because it is closer to the working directory, it overrides the root policy when the agent works in that subtree.

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
12
- Keep approval prompts on for all flag writes in this domain

Enterprise governance

On Business and Enterprise plans, Codex supports admin-enforced managed configuration through a requirements.toml file that Codex fetches from the Codex service and applies across the CLI, IDE, and cloud. Use it to keep the authoring-time boundary in place for every developer.

• Require a safe sandbox — Restrict the allowed sandbox modes so developers cannot run in full-access mode for routine work.
• Keep approvals on — Restrict the allowed approval policies so tool calls are not silently auto-approved.
• Allowlist the Unleash server — Define which MCP servers are permitted, so the Unleash server is available and unvetted servers are not.
• Control network access — Define network policy centrally for the sandbox.

This pairs with Unleash’s own governance. The MCP server inherits the PAT’s permissions and cannot exceed them, so scope the token tightly. Enable change requests on production environments so that enabling a flag requires human approval regardless of what any agent requests. Codex governs how the agent runs; Unleash governs how the release ships.

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.

Troubleshooting

Best practices

Follow these guidelines for effective feature flag management with Codex.

Related resources

• Unleash MCP server on GitHub
• OpenAI Codex documentation
• Codex MCP configuration
• Codex AGENTS.md guide
• Codex sandboxing
• Impact Metrics
• Unleash architecture overview