How to Add MCP Servers to OpenAI Codex

Short answer: To add MCP servers to Codex, run codex mcp add <name> -- <command> for a local server, or add a [mcp_servers.<name>] table with a url to ~/.codex/config.toml for a remote one. Then run /mcp inside Codex to see the server and codex mcp login <name> if it needs a sign-in.

MCP servers give an AI agent tools for other apps, such as your design files or a browser. If the idea is new, start with our guide on what MCP servers are. This post covers OpenAI Codex, OpenAI’s coding agent. If you are still choosing between agents, our Codex vs Claude Code comparison helps. To find servers worth adding, browse the full MCP servers directory.

Codex MCP setup at a glance

What you need first

• Codex installed. It runs in the cloud, the CLI, an IDE extension and a desktop app. The CLI, the extension and the app read the same MCP configuration.
• For a local server started with npx, Node.js on your machine. Check it with node --version.
• An account with the service behind the server, such as Figma. The servers on Klyvoo are free to connect, but they need that account where the vendor requires one.

The two kinds of MCP server Codex supports

OpenAI’s documentation lists two transports:

• STDIO: a local program that Codex starts with a command. Nothing is hosted for you, so it needs the tool installed or fetched by npx.
• Streamable HTTP: a server that lives at a URL. The vendor runs it, so there is nothing to install.

Our directory shows the transport on every server page, so you can tell which kind you are adding before you start.

How to add a local MCP server

Use codex mcp add, put the server’s name first and the command after a double dash:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

OpenAI’s own example adds Context7, which gives Codex current, version-specific library docs:

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

Playwright MCP follows the same pattern. Its command on our server page is npx @playwright/mcp@latest, so adding it to Codex looks like this:

codex mcp add playwright -- npx @playwright/mcp@latest

The -- separates Codex’s own options from the command that starts the server. Everything after it goes to the server untouched. Repeat --env once for each variable the server needs.

How to add a remote MCP server

For a server at a URL, pass --url:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

You only need --oauth-client-id when the server asks you to register your own OAuth client. For a typical server, --url alone is enough, because Codex registers itself during sign-in. If the server gives you a client secret, pass it from an environment variable and not as text in your shell history:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Sign in to a remote server

Run the login command with the name you gave the server:

codex mcp login <server-name>

Codex picks the client registration method for you, trying CIMD first and then DCR. To limit what you grant, add scopes, for example codex mcp login <name> --scopes read,write. A configured client ID skips registration.

Edit config.toml directly

Every server you add is stored in ~/.codex/config.toml as a [mcp_servers.<server-name>] table. You can write the same thing by hand. This is OpenAI’s example for a local server and a remote one:

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

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

The Figma MCP Server uses the remote URL shown here, and its page lists OAuth as the sign-in. Use bearer_token_env_var when you already have a token and would rather keep it in an environment variable than sign in through the browser.

The keys you will use most:

Add servers in the desktop app or IDE

You do not have to use the terminal. In the Codex desktop app, open Settings, then MCP servers, then Add server. In the IDE extension, open the gear menu, then MCP servers, then Add server. Because the app, the CLI and the extension share one configuration, a server added in one place shows up in the others.

Project-level config for a team

Besides the file in your home folder, Codex reads a .codex/config.toml in a project. OpenAI says this applies to trusted projects only, which stops a cloned repository from starting servers on your machine without your say-so. Put the shared servers there and keep tokens in environment variables, so the secret stays out of version control.

Check that it works

1. Run codex mcp list in your terminal to see every configured server.
2. Start codex and type /mcp to see which servers are active.
3. Ask Codex to do something only that server can do, such as “look up the latest docs for this library with Context7”.

Common errors and fixes

• The server does not appear in /mcp. Run the same command in your terminal to see the error. A missing Node.js is the usual cause for npx servers.
• A slow server fails at startup. The default startup wait is 10 seconds. Raise startup_timeout_sec for that server in config.toml.
• A long tool call is cut off. The default tool wait is 60 seconds. Raise tool_timeout_sec.
• A remote server asks you to sign in again. Run codex mcp login <name>.
• Your project’s .codex/config.toml is ignored. Project config loads only for trusted projects, so mark the project as trusted first.
• Codex shows too many tools. Use enabled_tools to keep only the ones you want, or disabled_tools to drop a few.

Which MCP servers to add first

Start with servers that match the work you do every day. These list Codex as a supported client on their Klyvoo pages:

• Context7: current library docs and code examples, so Codex stops guessing old APIs. Remote or local, and the sign-in is an optional API key.
• Playwright MCP: drives a real browser to click, type and read pages while you test. Local, no sign-in.
• Figma MCP Server: lets Codex read Figma designs for code and write to the canvas. Remote, with OAuth.

Add one or two, then watch how Codex uses them before you add more. Every server adds tools for the agent to choose from, and a short list keeps its choices sharp. Not every server lists Codex yet, so check the “works with” line on a server’s page before you add it. For more tools in this category, see our AI coding agents page.

What MCP servers in Codex cannot do

A server only exposes what its maker built, and only within what your account allows. A local server runs with your access, so read what a tool is about to change before you approve it. MCP also does not replace project notes. Rules about your codebase still belong in your repository’s instructions for the agent, not in a server.

If you also use other agents, the steps differ in each. We cover Claude Code and Claude on the web and Desktop in separate guides.

FAQ

How do I add an MCP server to Codex?

Run codex mcp add <name> -- <command> for a local server, or codex mcp add <name> --url <url> for a remote one. You can also add a [mcp_servers.<name>] table to ~/.codex/config.toml.

Where does Codex store MCP server settings?

In ~/.codex/config.toml, with one [mcp_servers.<name>] table per server. A trusted project can also have its own .codex/config.toml. The CLI, the IDE extension and the desktop app share the same configuration.

How do I see which MCP servers Codex is using?

Run codex mcp list in your terminal, or type /mcp inside the Codex terminal app or the desktop app’s composer. Both show the servers Codex has loaded.

Does Codex support remote MCP servers?

Yes. Codex supports Streamable HTTP servers at a URL as well as local STDIO servers. Add a remote server with --url, then sign in with codex mcp login <name> if it uses OAuth.

Do I need Node.js to use MCP servers in Codex?

Only for local servers that start with npx. Remote servers need no install, because you add them with a URL.

Are MCP servers free in Codex?

Adding a server costs nothing, and the servers listed above are free to connect. You still need an account with the service behind them where the vendor asks for one, and that service sets its own prices.

These commands come from OpenAI’s Codex MCP documentation, checked in October 2026. Options change between releases, so follow that page if a flag differs. For servers to try next, browse the Klyvoo MCP servers directory.