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.

Two Types of MCP Servers

STDIO Servers

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"]

Streamable HTTP Servers

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.

Tip

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"]

Tip

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

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_TOKEN = "ghp_your_token_here"

Caution

Do not commit your GitHub token to version control. Either use a project-scoped .codex/config.toml that is in .gitignore, or put the server definition in your user-level ~/.codex/config.toml.

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

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

Documentation Context (Context7)

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

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.

Tip

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