MCP Setup

You asked Codex to implement a feature using the latest React Server Components API, and it generated code using patterns from two years ago. You asked it to check your Sentry errors, and it said it cannot access external services. The problem is not the model — it is that Codex only sees your local filesystem by default. MCP (Model Context Protocol) servers extend what Codex can reach: live documentation, browser control, issue trackers, design tools, and more.

What You’ll Walk Away With

At least one MCP server configured and working across all surfaces
Understanding of STDIO vs Streamable HTTP server types
The config.toml configuration for common MCP servers (Context7, Playwright, GitHub, Figma, Sentry)
OAuth authentication set up for servers that require it
Confidence in managing, enabling, and disabling servers

What MCP Does for Codex

Without MCP, Codex can read files, run commands, and search the web (using its built-in web search). With MCP, Codex gets tools it can call: fetch up-to-date library documentation, take browser screenshots, read Figma designs, query Sentry logs, manage GitHub pull requests, and interact with any service that exposes an MCP interface.

All MCP configuration is shared across the App, CLI, and IDE extension. Configure once in config.toml, use everywhere.

STDIO servers run as a local process. Codex starts them with a command and communicates over standard input/output.

Examples: Context7, Playwright, Sentry, most open-source MCP servers.

Configuration requires a command and optional args, env, and cwd:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

HTTP servers run at a URL. Codex connects to them over HTTP(S) and optionally authenticates with a bearer token or OAuth.

Examples: Figma (remote), Chrome DevTools, custom internal servers.

Configuration requires a url and optional auth:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Add Your First MCP Server

The fastest way to add a server is the CLI command. Let us start with Context7, which gives Codex access to up-to-date documentation for popular libraries.

codex mcp add context7 -- npx -y @upstash/context7-mcp

That is it. Codex writes the server definition into ~/.codex/config.toml, and all surfaces pick it up immediately.

Prompt to verify your MCP server is working:

In the CLI TUI, type /mcp to see active servers. Or ask Codex directly:

What MCP servers do I have connected? List them with their status.

You should see context7 listed as connected.

Common MCP Server Configurations

Here are config.toml blocks for the most useful MCP servers, ready to paste.

Context7 — Library Documentation

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Prompt to use Context7:

After connecting, try:

Using Context7, look up the latest Next.js App Router documentation for server actions

Codex fetches current docs instead of relying on its training data.

Playwright — Browser Control

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]

Use Codex to open a browser, navigate to your app, take screenshots, and verify visual changes.

GitHub — Pull Requests and Issues

Use GitHub’s official, actively maintained github/github-mcp-server. The simplest path is the remote server with OAuth, which keeps no token in your config file:

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT"

Export a fine-grained personal access token in the named variable (export GITHUB_PAT=github_pat_...) before launching Codex. Prefer running the remote server with OAuth via codex mcp login github when available, so no token touches your shell at all.

If you need the server to run locally, use the official Go binary in Docker — note the env var is GITHUB_PERSONAL_ACCESS_TOKEN, not GITHUB_TOKEN:

[mcp_servers.github]
command = "docker"
args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

Figma — Design Access (Remote HTTP)

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Sentry — Error Logs

Sentry’s documented Codex setup is the hosted remote server, which handles auth through an OAuth flow in your browser — no token to manage:

codex mcp add sentry -- npx -y mcp-remote@latest https://mcp.sentry.dev/mcp

Run a Sentry query the first time and Codex opens a browser tab to authorize. If you must use the local stdio package (@sentry/mcp-server) instead, it requires an access token and host passed as args — source them from environment variables, never inline.

Configure via config.toml (Advanced)

For fine-grained control, edit ~/.codex/config.toml directly (or a project-scoped .codex/config.toml for team servers).

Each server is a [mcp_servers.<name>] table. Here is a fully annotated example:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled = true
enabled_tools = ["open", "screenshot", "evaluate"]
disabled_tools = ["screenshot"]          # Applied after enabled_tools
startup_timeout_sec = 20                 # Default: 10
tool_timeout_sec = 45                    # Default: 60

Tool Allow/Deny Lists

When an MCP server exposes many tools, you can restrict which ones Codex can use:

enabled_tools: Whitelist. Only these tools are available.
disabled_tools: Blacklist. Applied after the whitelist. Useful for removing specific tools.

Environment Variables

For STDIO servers that need secrets:

[mcp_servers.my_server]
command = "my-mcp-server"
env_vars = ["DATABASE_URL", "API_SECRET"]

env_vars tells Codex to forward specific environment variables from your shell to the server process. This is safer than hardcoding secrets in env.

OAuth Authentication

Some HTTP-based MCP servers use OAuth. Codex supports this natively:

codex mcp login figma

This opens a browser for the OAuth flow. After you authorize, Codex stores the token and uses it for future requests.

If your OAuth provider requires a static callback URI, set:

mcp_oauth_callback_port = 8080

By default, Codex binds to an ephemeral port.

Managing Servers

# List all configured servers
codex mcp list

# Remove a server
codex mcp remove context7

# Disable without removing (edit config.toml)
# Set enabled = false under the server table

In the Codex App, open Settings > MCP to see all servers, toggle them on/off, and add new ones from recommended suggestions.

In the CLI TUI, use /mcp to see server status.

Prompt to test all MCP servers at once:

List all my connected MCP servers and call one tool from each to verify they're working

This is a quick health check that exercises every connected server.

When This Breaks

Server fails to start: Check that the command exists. For npx servers, ensure Node.js 18+ is installed and npx is in your PATH. Increase startup_timeout_sec if the server takes a while to initialize.

“Tool not found” errors: The server may have started but its tools were not registered. Run codex mcp list to check. If tools are missing, the server might need environment variables or configuration that is not set.

OAuth flow does not complete: Check that your browser can reach the OAuth provider. If you are behind a corporate proxy, the callback URL may be blocked. Try setting mcp_oauth_callback_port to a port your proxy allows.

Servers work in CLI but not in the App: All surfaces share the same config, but the App may need a restart to pick up changes. Close and reopen the App after adding servers.

MCP server crashes mid-task: Codex should report the failure and continue working without the server. The task may fail if it critically depends on the server’s tools. Restart Codex to reconnect.

Timeout errors: Increase tool_timeout_sec for slow operations (e.g., browser screenshots, large API responses).

What’s Next

Connect GitHub Set up GitHub integration for PR workflows and @codex mentions