Integrate Unleash with OpenAI Codex for AI-powered feature flag management

The Unleash MCP server connects OpenAI Codex to your Unleash instance, enabling AI-assisted feature flag management. This page covers how to install and configure the server in Codex. To learn what the server can do, see Unleash MCP server.

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.

This guide covers the local Unleash MCP server, a stdio process that runs in the Codex CLI and IDE extension. It is the simplest setup and the focus of this page.

Unleash also offers a remote MCP server (Streamable HTTP, available on Enterprise plans), which matters for Codex cloud agents that run in a network-isolated sandbox that cannot run a local stdio server. Codex can connect to a remote HTTP MCP server. Remember to enable internet access for the environment and add your Unleash host to the allowlist for both read and write methods (GET, POST, PATCH, DELETE) so flag changes work too.

If you are not using cloud tasks, use the local setup below to manage flags from your machine.

Prerequisites

Before you begin, make sure you have the following:

Node.js 24 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

You must sign in before the agent can call MCP tools. You can add the server and run codex mcp list before signing in, but the first tool call in an unauthenticated session fails with a 401 error. Run codex login first.

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.

Create a credentials file

Store your Unleash credentials in a centralized file and source it from your shell profile:

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

Add to your ~/.zshrc or ~/.bashrc:

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

Restart your terminal or run source ~/.zshrc to load the variables.

Variable	Description	Required
`UNLEASH_BASE_URL`	Your Unleash instance URL, without a trailing `/api`.	Yes
`UNLEASH_PAT`	A personal access token with flag creation permissions.	Yes
`UNLEASH_MCP_SEND_FEEDBACK`	Set to `true` or `false` to opt in to or out of feedback reports without a consent prompt. With `false`, the assistant doesn’t see the `send_feedback` tool.	No

Add the server with the CLI

Run codex mcp add from your project root. This writes the server configuration to ~/.codex/config.toml:

codex mcp add unleash \
  --env UNLEASH_BASE_URL="$UNLEASH_BASE_URL" \
  --env UNLEASH_PAT="$UNLEASH_PAT" \
  -- npx -y @unleash/mcp@latest

Alternatively, edit ~/.codex/config.toml directly:

~/.codex/config.toml

[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" }

Codex uses TOML with a [mcp_servers.unleash] table (note the underscore in mcp_servers). The command is a string and args is an array. The env table holds literal values and does not perform ${VAR} expansion. To forward a variable from your shell instead, use the env_vars key (an array of names) rather than env.

You can also write env as a subtable, which is easier to read for several variables:

~/.codex/config.toml

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

Verify the installation

Confirm the server is registered:

codex mcp list      # shows: unleash
codex mcp get unleash

Then start a session and ask: “What Unleash MCP tools are available?” The agent lists every available tool. Codex prefixes MCP tool names with the server name, so the Unleash tools appear as unleash/search, unleash/release, and so on.

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 "search"?
  › 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 release or kill_switch, 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.

In non-interactive codex exec, the approval prompt cannot be shown, so MCP tool calls are auto-cancelled with the message user cancelled MCP tool call. There is currently no configuration that pre-approves an MCP server while keeping the sandbox (this is a known open issue).

For automation, run codex exec with --dangerously-bypass-approvals-and-sandbox inside an isolated runner with a tightly scoped PAT. For day-to-day flag work, use an interactive session and approve the prompts.

Tools and workflows

Once the server is connected, Codex can use every tool the Unleash MCP server exposes. To learn what the server can do and see step-by-step workflows, read Unleash MCP server. For the current list of tools, see the README on GitHub.

Feedback reports

The first time the assistant tries to send a feedback report, Codex shows a consent prompt with the default on-request approval policy. The MCP server saves whether you opted in or out, so you see the prompt only once.

With the following approval policies, Codex accepts or declines the consent prompt for you, and the MCP server saves that choice:

approval_policy = "never"
A granular approval policy that sets mcp_elicitations = false

To make the decision yourself with these policies, or to skip the prompt, pass --env UNLEASH_MCP_SEND_FEEDBACK=true or --env UNLEASH_MCP_SEND_FEEDBACK=false to codex mcp add, or add the variable to the env table in ~/.codex/config.toml. To learn what a report contains, see What is recorded.

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.

Troubleshooting

401 errors on every tool call

The agent is not signed in. Run codex login and sign in with your ChatGPT account, or configure an API key. codex mcp list can show the server as registered before you sign in, but tool calls fail with a 401 until you authenticate.

'user cancelled MCP tool call' in codex exec

Non-interactive codex exec cannot show the approval prompt, so approval-required calls are auto-cancelled. Run an interactive session and approve the prompt, or use --dangerously-bypass-approvals-and-sandbox for automation inside an isolated runner. This is a known open limitation; a per-server auto-approve setting is proposed but not yet available.

MCP server not appearing in Codex

Verify ~/.codex/config.toml for TOML syntax errors
Confirm the table is [mcp_servers.unleash] with an underscore in mcp_servers
Confirm command is a string and args is an array
Run codex mcp list to check the server status
Restart Codex after making changes

Authentication or API errors

Confirm your Unleash PAT is valid and has not expired
Check that the PAT has permissions to create and manage feature flags
Verify that UNLEASH_BASE_URL does not include /api at the end (the server appends it, and a trailing /api produces doubled /api/api/ paths)
Test directly: curl -H "Authorization: $UNLEASH_PAT" "$UNLEASH_BASE_URL/api/admin/projects"

Environment variables not applied

The env table in config.toml holds literal values and does not expand ${VAR} references
To forward a shell variable, use env_vars = ["VAR_NAME"] (an array) instead of env
If you used codex mcp add with --env, the values are written literally into config.toml

Node.js not found

Local servers using npx require Node.js 24+. Verify with node --version. If Node.js is installed but not found by Codex, check that Codex inherits your shell PATH.

Codex cloud agent cannot reach Unleash

Cloud sandboxes are network-isolated by default, and they cannot run a local stdio MCP server. You have two options:

Run flag operations in the CLI or IDE extension (recommended for most teams), then let cloud tasks open pull requests that ship behind the flags you created.
Use the remote Unleash MCP server (Enterprise), which Codex connects to by url. Enable internet access for the cloud environment, add your Unleash host to the allowlist, and allow write methods (POST, PATCH, DELETE) so flag changes work. Verify the remote server’s authentication flow works in a headless environment before relying on it.

Feedback is disabled

send_feedback returns this message if you declined the consent prompt, if Codex declined it for you, or if UNLEASH_MCP_SEND_FEEDBACK is set to false. To opt in, add UNLEASH_MCP_SEND_FEEDBACK = "true" to the env table of [mcp_servers.unleash] in ~/.codex/config.toml and restart Codex. To see the consent prompt again, delete feedback_consent.json from the configuration directory. Feedback settings don’t affect flag operations.