↑↓ to move↵ to openSearch by Pagefind
 Get Started
← All guides
Recipe

Connect OpenAI Codex to MCP servers

Add MCP servers to Codex with the codex mcp add command or by editing config.toml, sign in to hosted servers, and check what is connected with /mcp.

Beginner 7 min read 5 Nov 2026 OpenAI Codex

Codex can read and edit your files, but MCP servers let it reach further: look up current library docs, drive a browser, read your tickets. MCP (Model Context Protocol) is an open standard for plugging tools into AI apps. This recipe shows two ways to add a server to Codex. It assumes Codex is installed. New to the idea? Read what an MCP server is first.

Option 1: the codex mcp add command

A local server (it runs on your computer)

codex mcp add <server-name> -- <command to start the server>

The double dash (--) matters. Everything before it is for Codex. Everything after it is the exact command that starts the server. A real example from OpenAI's docs adds Context7, which gives Codex up-to-date library documentation:

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

To pass an environment variable to a local server, add --env before the dash-dash:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <command to start the server>

A hosted server (it lives online)

Use --url instead of a command. Figma's own instructions for Codex are:

codex mcp add figma --url https://mcp.figma.com/mcp

Figma then asks you to sign in and allow access. Many hosted servers use OAuth (a browser-based "log in with…" flow). If you need to start that flow yourself, run:

codex mcp login <server-name>

On a machine with no local browser, add --no-browser. Codex prints a URL, you sign in on another device, then paste the full redirect URL back into the terminal.

Check what's connected

codex mcp list

Run codex mcp --help to see every MCP command. Inside a Codex session, /mcp lists the MCP tools Codex can currently use.

Option 2: edit config.toml

The commands above write to Codex's config file, ~/.codex/config.toml. You can edit it by hand instead. Each server gets its own [mcp_servers.<name>] block.

A local server:

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

A hosted server that needs a token. Keep the token in an environment variable and give Codex only the variable's name:

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

That GitHub block is from GitHub's own Codex install guide. Set GITHUB_PAT_TOKEN in your shell first, using a token with the narrowest permissions you can. See the GitHub server page.

A hosted server that signs in with OAuth needs only a URL, then codex mcp login. Notion's docs use exactly this:

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

codex mcp login notion

Codex's docs also describe a project-level .codex/config.toml for sharing a setup with your team. They say it applies to trusted projects only.

Servers worth trying first

Don't install everything. Each server adds tools Codex has to consider. Pick one or two that match a job you actually do:

Every server page lists the Codex setup where the server's own docs cover it. Browse the whole MCP directory.

Staying safe

  • Use servers from sources you trust. Official ones from the vendor are the safest.
  • Least privilege. Create tokens with minimum permissions and expiry dates, and use read-only modes where offered.
  • Don't commit secrets. Use bearer_token_env_var or --env rather than pasting tokens into a file that goes into Git.
  • Read approval prompts. Codex's docs describe per-server and per-tool approval settings, so you can require a prompt before a tool runs.

Troubleshooting

The server doesn't start. Run its command directly in a terminal to see the error. Missing Node.js (for npx servers) is the usual cause.

A startup timeout. Codex's docs list a startup_timeout_sec setting for each server. Context7's own guide suggests raising it if you see timeout errors on a slow first start.

Sign-in fails for a hosted server. Run codex mcp login <server-name> again, and check /mcp afterwards.

Recap

  1. Local server: codex mcp add <name> -- <command> <args>.
  2. Hosted server: codex mcp add <name> --url <url>, then codex mcp login <name> if it uses OAuth.
  3. Or edit [mcp_servers.<name>] blocks in ~/.codex/config.toml.
  4. Check with codex mcp list and /mcp.
  5. Keep tokens minimal and secret.