How to set up the GrowthBook MCP server for Codex

The command is short. The setup is only complete when Codex can discover the current GrowthBook skills, authenticate, and return the right project without exposing your token.

Codex and GrowthBook now support a cleaner connection than the older copy-paste JSON examples suggest. Codex can add a local stdio server from its command line, desktop settings, IDE extension, or config.toml. GrowthBook's current @growthbook/mcp 2.0 server exposes 3 prefixed capabilities: list bundled skills, read a selected skill, and call the authenticated GrowthBook REST API. That connection brings the GrowthBook MCP workflow into the same environment where Codex reads and changes your code.

That version detail matters. The GrowthBook MCP documentation still shows the earlier fixed tool catalog and configurations that include GB_EMAIL. The current version 2 server source uses GB_API_KEY as the required credential for local stdio, with GB_API_URL optional for self-hosted instances. Its bundled skills contain the workflow logic for creating flags, launching experiments, analyzing results, auditing metrics, and building charts.

This guide follows the current server package and Codex's current MCP configuration. It also separates 2 choices teams often mix together: connecting the MCP server, and installing GrowthBook's standalone agent skills. The server already bundles skills. You can install the standalone GrowthBook skills repository separately when you want direct REST workflows without MCP, but it is not required for the MCP connection below.

Check the prerequisites before editing configuration

You need 4 things:

1. A local Codex client. The ChatGPT desktop app, Codex CLI, and Codex IDE extension can connect to MCP servers and share host configuration. ChatGPT web does not read your local Codex config file.
2. Node.js 18 or later. The npx command downloads and runs the published GrowthBook package. Check with node -v and npx --version.
3. A GrowthBook account or self-hosted instance. The MCP server calls your GrowthBook API; it does not create a separate workspace.
4. A dedicated GrowthBook credential. Prefer a personal access token (PAT) you can revoke independently. Do not reuse a broad admin token for an editor integration.

The current package on npm is @growthbook/mcp. Verify the package name against the official npm listing or the GrowthBook-owned GitHub repository before running it. MCP packages execute locally with the privileges of your user account, so package identity is part of the security review.

Choose the credential scope first

A read-only pilot only needs permissions to inspect the projects, flags, experiments, metrics, and analytics objects in scope. A token used to create or publish flag revisions needs broader permissions. Keep those use cases separate if your organization can issue different credentials.

The agent should never need the token in the conversation. Supply it through Codex's MCP environment configuration or forward it from a local environment variable. If a token is ever pasted into a prompt, terminal transcript, screenshot, or support ticket, revoke it and create a new one.

Decide between user-level and project-level configuration

The official Codex MCP guide stores user configuration in ~/.codex/config.toml. You can also add .codex/config.toml to a trusted project when the connection belongs only to that repository.

Use user-level configuration when the same GrowthBook account and permissions should be available across projects. Use project-level configuration when a repository needs a specific self-hosted URL, stricter tool policy, or isolated credential. A project-level config should never be committed with a secret.

Add GrowthBook with the Codex CLI

The shortest current command is:

codex mcp add growthbook --env GB_API_KEY=YOUR_GROWTHBOOK_PAT -- npx -y @growthbook/mcp@latest

For a self-hosted instance, add the API base URL:

codex mcp add growthbook \
  --env GB_API_KEY=YOUR_GROWTHBOOK_PAT \
  --env GB_API_URL=https://growthbook-api.example.com \
  -- npx -y @growthbook/mcp@latest

The command structure follows Codex's documented pattern: codex mcp add, the server name, zero or more environment values, --, then the stdio command and arguments. GrowthBook Cloud defaults to https://api.growthbook.io, so cloud users do not need GB_API_URL.

There are 2 security tradeoffs to understand:

• --env GB_API_KEY=... is convenient, but it places the value in Codex's persisted MCP configuration.
• Forwarding GB_API_KEY from the process environment avoids putting the literal value in config.toml, but the desktop app must start with access to that environment variable.

Choose the method that matches your endpoint-management and secrets policy. In either case, use a revocable PAT with the least privilege required.

Plan feature flags at scale

Connect agent workflows to a flag program with clear ownership, lifecycle rules, and progressive-delivery guardrails.

Read the Feature Flag Guide

Configure GrowthBook in the desktop app or IDE

Codex's desktop and IDE interfaces can create the same connection without a terminal command. According to the official Codex setup steps, open Settings, choose MCP servers, select Add server, and choose STDIO.

Enter these values:

• Name:growthbook
• Command:npx
• Arguments:-y, @growthbook/mcp@latest
• Environment:GB_API_KEY; add GB_API_URL only for self-hosted

Save the server and restart the client. In the IDE extension, restart the extension. The desktop app, CLI, and IDE extension share configuration for the same Codex host, so a user-level server should not need to be added 3 times.

Windows users who see npx start failures can use cmd as the command with /c, npx, -y, and @growthbook/mcp@latest as arguments. This mirrors the Windows command wrapper in GrowthBook's older editor examples. Before changing the configuration, confirm that node, npm, and npx resolve in the same environment from which Codex starts.

Use config.toml for explicit policy

Direct configuration gives you control over timeouts, required startup, tool allowlists, and approval behavior. A minimal local server looks like this:

[mcp_servers.growthbook]
command = "npx"
args = ["-y", "@growthbook/mcp@latest"]
env_vars = ["GB_API_KEY", "GB_API_URL"]
startup_timeout_sec = 20
tool_timeout_sec = 60
required = false
default_tools_approval_mode = "writes"

The env_vars list tells Codex which existing environment values it may forward. The writes approval mode prompts for tools that are not marked read-only. GrowthBook's generic API tool also instructs the agent to confirm mutating POST, PUT, PATCH, and DELETE calls unless the user already authorized them. Treat both as defense in depth, not as a substitute for restricted credentials.

If you put a literal token under [mcp_servers.growthbook.env], keep the file local and limit access. Do not commit the token in a project-scoped config.

Pin a package version when reproducibility matters

@latest follows new stable releases. That is convenient for individuals testing the integration, but regulated or centrally managed environments may want a reviewed version:

args = ["-y", "@growthbook/mcp@2.0.0"]

The GrowthBook release process publishes tagged npm packages, container images, MCP Registry entries, and GitHub releases. Review the changelog and bundled skill changes before advancing a pinned deployment.

Verify the server in 3 layers

A green status only proves that the process initialized. Verify transport, authentication, and workflow behavior separately.

1. Confirm Codex can see the server

Run:

codex mcp list

You can also use /mcp in the Codex terminal interface or open MCP servers in desktop or IDE settings. The server should appear as enabled. If it failed to start, check the command path, Node version, startup timeout, and whether another configuration with the same name is taking precedence.

Community reports often focus on this layer because a server may appear in one client but not another. Codex now documents shared host configuration, but project-scoped files only apply when the project is trusted and actually open. Do not diagnose an authentication problem until the client shows that the server initialized.

2. Confirm GrowthBook authentication

Ask Codex:

Use the GrowthBook MCP server. List my GrowthBook projects and environments. Do not make any changes.

The current server should discover the relevant skill, read its workflow, and call the API. A 401 indicates an invalid, expired, or revoked token. A 403 usually means the token is valid but lacks permission for that operation. A cloud user pointing at a self-hosted URL, or a self-hosted user relying on the cloud default, will typically see a routing or resource error. If the token spans several organizations or projects, name the intended project in the prompt and require Codex to echo the resolved ID before continuing.

3. Confirm the skill-driven workflow

Ask:

List the available GrowthBook skills. Then explain which skill you would use to audit feature flags. Do not call any write endpoint.

The current server should expose growthbook_list_skills and growthbook_read_skill, plus growthbook_call_api. It should identify flag-search for a read-only audit. The bundled GrowthBook agent skills provide the workflow and guardrails; the API bridge performs the requested read or write. If you instead see the older fixed functions such as get_feature_flags, you may be running an earlier package version or reading stale documentation.

Finish with a bounded read:

Search feature flags in project <project> and environment <environment>. Return the flag IDs, owners, and live state. Do not create, update, archive, publish, or delete anything.

Compare the result with the GrowthBook feature flag UI. Correct project and environment resolution matter more than a polished summary.

For an experiment-focused verification, ask Codex to summarize one stopped experiment without starting a fresh snapshot. Check that it distinguishes metadata from current results, names the primary and guardrail metrics, and does not turn statistical uncertainty into a shipping command. GrowthBook's experimentation platform can expose rich result context, but the agent still needs a precise analysis workflow to interpret it responsibly.

Troubleshoot the failures that look alike

MCP setup errors often produce the same symptom: no useful tools. Work from the bottom of the stack upward.

When npx is not found

Run node -v, npm -v, and npx --version in the same shell or desktop environment that starts Codex. Reinstall a supported Node.js release or use an absolute command path. On Windows, try the cmd /c npx ... wrapper.

The server times out during startup

The first npx run may download the package. Increase startup_timeout_sec from the documented 10-second default to 20 or 30 seconds, then restart. Network filtering or a private npm registry may also block the package.

Authentication fails

Check that GB_API_KEY reached the server and does not contain whitespace. Revoke a possibly exposed token rather than trying to salvage it. For self-hosted GrowthBook, ensure GB_API_URL is the HTTPS API base URL with no /api/v1 or /api/v2 suffix.

The agent can read but cannot write

That is usually a permission or approval boundary, not a transport failure. Confirm the PAT's GrowthBook role, the target project's permissions, Codex's server approval mode, and whether the selected skill requires a draft or review step. Do not fix a permission error by switching to an unrestricted admin token.

The agent uses outdated tool names

Start a fresh Codex task after upgrading the package, then ask it to list the live server capabilities. Version 2 is skill-driven. Prompts copied from the older fixed-tool documentation may not match the current surface, although the underlying workflows remain available through skills and the REST bridge.

Run a safe first workflow

The best first workflow is read-only and easy to compare with the UI. Use flag-search to inspect a small project, or metric-search to list chartable fact metrics. Ask Codex to state the skill it selected, the identifiers it resolved, and the calls it made.

After that works, try a reversible write in a non-production project:

Create a Boolean feature flag named mcp-setup-check in project <sandbox-project>. Keep it disabled in every environment. Show me the exact proposed API action and wait for confirmation before writing.

GrowthBook's current flag-creation workflow checks for ID collisions, confirms the value type and project, creates the flag disabled everywhere, and reads it back. Delete or archive the test through the proper cleanup workflow once the team has reviewed the receipt.

The setup is successful when the server starts, the token resolves the intended GrowthBook account, the current skills are discoverable, and a bounded read returns the same state you see in GrowthBook. Only then should you expand permissions or automate a lifecycle.

Prevent false positives

Add the statistical checks and operating discipline that keep higher experiment velocity from turning into unreliable decisions.

Read the Prevention Playbook