Wiring feature flags into OpenAI Codex: From config.toml to controlled rollouts

The first post in this series made the case for two boundaries. Codex governs the agent while it writes code, through an operating-system sandbox and an approval prompt. Unleash governs the code after it ships, through feature flags.

This post is the hands-on half. We will connect the Unleash MCP server to Codex, get the agent creating and wrapping flags as part of normal work, and then make that behavior automatic and enforceable for a team.

You can follow along in the Codex CLI or the editor extension. The setup is the same for both, because they share one configuration file.

What you need

• Node.js 18 or newer. The MCP server runs through npx locally.
• Codex, signed in. Install the CLI, then run codex login and sign in with your ChatGPT account.
• An Unleash instance and a personal access token. Cloud or self-hosted, with a token that can create and manage flags.

Step 1: Connect the MCP server

Codex keeps its configuration in ~/.codex/config.toml. The fastest way to add the Unleash server is the CLI helper, which writes the right block for you:

codex mcp add unleash \
  --env UNLEASH_BASE_URL="https://your-instance.getunleash.io" \
  --env UNLEASH_PAT="your-personal-access-token" \
  --env UNLEASH_DEFAULT_PROJECT="default" \
  -- npx -y @unleash/mcp@latest

If you would rather edit the file directly, the block looks like this:

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

Note that the table is mcp_servers with an underscore (not camelCase). The command is a string and args is an array. And env holds literal values (no ${VAR} style expansion). If you need to forward a variable from your shell instead of writing it inline, that is a separate key (env_vars, an array of names).

Confirm the server is wired up:

codex mcp list
codex mcp get unleash

Step 2: Your first flagged change

Open Codex and describe a change you would actually want behind a flag:

Evaluate whether adding the new ACME shipping provider should be behind a feature flag. It changes how we fetch shipping rates at checkout.

Codex calls the Unleash tools in sequence. It evaluates the change, checks whether a similar flag already exists so it does not create a duplicate, and if none does, proposes creating one.

Here is where Codex’s approval prompt shows up, and it is worth pausing on, because this is the authoring boundary in action. Before the agent runs the tool, it shows you what it is about to do:

Allow the unleash MCP server to run tool "create_flag"?

  name: shipping-acme-provider
  type: release
  project: default

  › 1. Allow
    2. Allow for this session
    3. Always allow
    4. Cancel

You see the flag name, the type, and the project before anything happens. For a read-only lookup you can pick “Always allow” and stop thinking about it. For a write like this one, leaving the prompt on means a human signs off on every flag that gets created or toggled.

Approve it, and Codex creates the flag and wraps the new code:

if (unleash.isEnabled("shipping-acme-provider", context)) {
  return acmeShipping.getRates(order);
} else {
  return currentShipping.getRates(order);
}

The flag is created, disabled by default. The change can merge and deploy without exposing anything, and you decide when to turn it on. That is the whole point: shipping the code and releasing the feature are now two separate decisions.

The same tools cover the rest of the lifecycle. You can ask Codex to list and audit your flags, check the state of a specific one, enable it in staging, or clean it up once a feature has fully rolled out and the old code path is dead. Each write goes through the same approval prompt.

Step 3: Make it automatic with AGENTS.md

So far this works because you asked. The next step is making the agent consider flags on its own, so a developer does not have to remember the workflow. Codex reads an AGENTS.md file for project instructions, and that is where your team’s FeatureOps policy belongs.

Drop an AGENTS.md at the repo root:

# Feature Flag Conventions

Before implementing high-risk changes (payments, authentication, data
migrations, external integrations), use the Unleash MCP server to evaluate
whether a feature flag is needed.

- Naming: {domain}-{feature}-{variant}, e.g. checkout-stripe-integration
- Types: release, experiment, operational, kill-switch, permission
- Run detect_flag before creating a new flag to avoid duplicates
- Clean up flags that have been at 100% for two weeks or more

Now when a developer asks Codex to “add SSO login with Google,” the agent recognizes an authentication change, evaluates it against the policy without being told, and proposes a flag named the way your team names things.

Codex reads AGENTS.md from a global location down through your repository, and files closer to the working directory win, so you can put stricter rules in a subdirectory. A payments/AGENTS.md that says “every change here needs a kill-switch flag, no exceptions” overrides the gentler root policy for that part of the codebase.

Because AGENTS.md lives in version control, every developer who clones the repo gets the same behavior. The policy is code, not tribal knowledge.

Step 4: Mind the two boundaries

Codex runs in a sandbox. The default mode lets the agent read and write inside your workspace, and we confirmed that the Unleash MCP server reaches your Unleash instance just fine in that mode. You do not need to weaken the sandbox to manage flags. If you find yourself reaching for full-access mode to “make MCP work,” stop, because that is almost certainly an approval issue, not a network one.

The approval prompt is the other half. Interactively, it does exactly what you want: it pauses on writes and shows you the arguments. The rough edge today is non-interactive use. If you try to run flag operations through codex exec in a script or CI job, the agent has no terminal to show the prompt on, so the tool calls get auto-cancelled.

As of this writing there is no clean configuration to pre-approve a specific MCP server while keeping the sandbox, and it is an open issue on the Codex repo. The blunt workaround is to bypass approvals and the sandbox together, which is fine inside a locked-down CI runner with a tightly scoped token but is not something to reach for casually. This area is actively moving, so by the time you read this it may have a proper answer. For interactive development, none of this matters, and interactive development is where most flag work happens anyway.

The takeaway: keep the sandbox at its sensible default, keep approvals on for writes, and treat headless flag automation as an advanced case that needs deliberate setup.

Step 5: Enforce it for the team

Habits do not scale. Policy does.

Both pieces of this setup can be made organization-wide.

The AGENTS.md file and your MCP configuration both belong in version control, so a new developer is set up the moment they clone the repo and add their own credentials. On top of that, Codex supports admin-enforced configuration that applies across the CLI, the editor extension, and the cloud. A platform team can require a particular sandbox mode, keep approval prompts on, and define which MCP servers are allowed, so the Unleash server is permitted and random unvetted ones are not. Developers cannot quietly turn the guardrails off.

Unleash carries the other half of the governance. The access token scopes what the agent can touch. Change requests can require human approval before a flag flips on in production, no matter what an agent asks for. So even an “always allow” decision in Codex does not translate into unreviewed production changes, because the second boundary has its own gate.

This matters most for the work you do not watch. Codex can run tasks asynchronously and hand you back a pull request, and when you review that PR you are looking at an outcome, not a process you observed. If the change is already wrapped in a flag, it merges as disabled and you control the rollout, exactly as you would for a teammate’s code.

What you built

Five layers, each useful on its own:

1. The MCP server gives Codex the tools to automatically evaluate, create, wrap, audit, and clean up flags.
2. A first flagged change shows the automation working, with Codex’s approval prompt keeping you in control.
3. AGENTS.md makes the agent apply your flag policy without being asked.
4. The sandbox and approval model keeps the agent governed while it writes, with the default sandbox being all you need.
5. Admin config and Unleash governance make both boundaries enforceable across the team.

Start with the first two and a few manual runs. Add AGENTS.md when you notice naming drift. Bring in admin enforcement when more than a handful of people are doing this. Each step stands on its own, and together they give you AI that writes code fast and ships it behind a switch you control.

For the full configuration reference, the complete tool list, and troubleshooting, see our OpenAI Codex integration documentation and the Unleash MCP server repository.