How to add MCP servers to OpenAI Codex

Add MCP servers to OpenAI Codex with codex mcp add or a [mcp_servers] table in ~/.codex/config.toml, shared by the CLI, IDE extension and desktop app.

Local servers: Yes; runs stdio servers
Hosted servers: Yes; connects by URL
Config: TOML; how servers are added
Plugins: Yes; plugin marketplaces
Picks: 10; ranked

Run codex mcp add <name> -- <command> for a local server or codex mcp add <name> --url <address> for a hosted one, and Codex writes it to ~/.codex/config.toml. The Codex CLI, the IDE extension and the ChatGPT desktop app all read that file, so you set a server up once. A trusted project can also keep its own servers in .codex/config.toml.

Good for

Developers who want Codex to reach docs, GitHub, Sentry or a browser
Teams that want one project to carry its own servers in .codex/config.toml
People scripting Codex with codex exec in CI who need servers to load
Claude Code or Cursor users moving their setup to Codex

Install OpenAI Codex

Codex

Copy this prompt.

Add the OpenAI Codex MCP server to Codex. Run this command:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Then check that it loaded and tell me if I need to sign in or restart.

2
Paste it into Codex. It shows the change and asks before running it.

Then run codex in a project folder and choose Sign in with ChatGPT or another sign-in method.

From the vendor's docs. Source.

At a glance

Add a local server: codex mcp add <name> -- <command>
Add a hosted server: codex mcp add <name> --url <address>
Config file: ~/.codex/config.toml, [mcp_servers.<name>]
Project config: .codex/config.toml (trusted projects only)
Shared by: Codex CLI, IDE extension, ChatGPT desktop app
Sign in: codex mcp login <name>
Check servers: codex mcp list, or /mcp in the TUI
Default timeouts: 10 s startup, 60 s per tool call
Scripted runs: codex exec "<task>" (read-only sandbox by default)
Resume: codex resume, codex resume --last, codex exec resume --last

Add an MCP server to Codex

ChatGPT

Add a local server with codex mcp add

Put the launch command after --. Pass keys with --env.

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add <server-name> --env VAR1=VALUE1 -- <stdio server-command>

Uses Context7

2
Or add a hosted server by URL
```
codex mcp add example --url https://mcp.example.com
```
If the server uses sign-in, run codex mcp login example next. If the provider gave you a client ID, add --oauth-client-id my-client.

Or edit config.toml by hand

Open ~/.codex/config.toml (all projects) or .codex/config.toml in a trusted project. Each server is a [mcp_servers.<name>] table:

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

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

Uses Figma MCP Server

4
Limit tools and approvals if you want
Use enabled_tools or disabled_tools to pick tools, and default_tools_approval_mode = "writes" to make Codex ask before tools that are not marked read-only. Set enabled = false to switch a server off without deleting it.
5
Check it loaded
Run codex mcp list in your shell, or type /mcp inside the codex terminal app to see active servers.

Use it in a prompt

Start codex in your project and ask for the job.

Prompt

Use context7 to look up the current Next.js docs for server actions, then update app/actions.ts to match.

Uses Context7

7
In the IDE extension or desktop app
IDE extension: gear menu, MCP servers, Add server, choose STDIO or Streamable HTTP, save, then Restart extension. ChatGPT desktop app: Settings, MCP servers, Add server, save, then Restart. Both use the same config file as the CLI.

Best MCP servers for OpenAI Codex

Official servers with an approved PlugWiki page whose setup for this client is documented by the vendor or client; ordered by GitHub stars, then weekly downloads, then name.

MCP servers that work in OpenAI Codex

40 · official first, then servers with a page, then by stars

Show all 40

Common errors and fixes

Server times out on startup
Cause: Codex waits 10 seconds by default, and npx can take longer the first time.
Fix: Set startup_timeout_sec = 20 (or more) in the server's [mcp_servers.<name>] table.
codex Source
Project .codex/config.toml servers do not load
Cause: Codex reads project config only in trusted projects.
Fix: Trust the project, or add the server to ~/.codex/config.toml instead.
codex Source
codex mcp login does nothing for a server
Cause: Sign-in only works for servers added by URL that support OAuth.
Fix: For key-based servers, set bearer_token_env_var or http_headers instead.
codex Source
codex exec stops with an MCP error
Cause: A server marked required = true failed to start.
Fix: Fix the server, or remove required = true so the run continues without it.
codex Source
codex exec cannot edit files
Cause: codex exec runs in a read-only sandbox by default.
Fix: Pass --sandbox workspace-write; --full-auto is no longer supported.
codex Source
codex mcp-server command not found
Cause: The command was removed.
Fix: Use the Codex app server to control Codex from another program.
codex Source

Verdict

Codex gives you one MCP setup in config.toml that the CLI, IDE extension and ChatGPT desktop app all share, with per-tool approval controls. The main limit is short default timeouts, 10 seconds to start, so slow npx servers may need startup_timeout_sec raised.

Best for

Developers using Codex in the terminal, IDE or ChatGPT desktop app
Teams scripting Codex with codex exec in CI

Skip it if

You expect servers in a project .codex/config.toml to load in an untrusted project
You want a JSON config you can copy from another app unchanged

Questions

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 <address> for a hosted one. Check it with codex mcp list.

Where is the Codex MCP config file?

~/.codex/config.toml, under [mcp_servers.<name>] tables. A trusted project can also have .codex/config.toml with servers only for that project.

Does Codex use JSON or TOML for MCP servers?

TOML. Servers you install through a Codex plugin can declare theirs in the plugin's .mcp.json, but your own servers go in config.toml.

What does codex exec do?

codex exec "<task>" runs Codex once without the interactive screen, for scripts and CI. It prints only the final answer to stdout, runs in a read-only sandbox unless you pass --sandbox workspace-write, and --json streams events as JSON lines.

How do I resume a Codex session?

Run codex resume to pick a recent chat, codex resume --last for the latest one in this folder, or add --all to search every folder. For scripted runs use codex exec resume --last "<next prompt>" or codex exec resume <SESSION_ID>.

How do I sign in to an MCP server that uses OAuth?

Run codex mcp login <server-name>. It works only for servers added by URL that support sign-in. Use --scopes read,write to ask for specific permissions.

Why does my MCP server time out in Codex?

Codex waits 10 seconds for a server to start and 60 seconds per tool call by default. Raise startup_timeout_sec or tool_timeout_sec in that server's table.

Will codex exec fail if an MCP server does not start?

Only if you set required = true on that server. Then codex exec exits with an error instead of running without it.

Can I bring my Claude Code setup into Codex?

Yes. Type /import in the codex terminal app, choose Claude Code or Cursor, and pick what to bring over.

What happened to codex mcp-server?

It was removed. OpenAI points to the Codex app server instead if you want to drive Codex from another program.

Information

updated Nov 1, 2026

Transports: stdio, Streamable HTTP
Config file (all): ~/.codex/config.toml
MCP docs: developers.openai.com

Website Docs

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

Codex CLI · learn.chatgpt.com
Model Context Protocol · learn.chatgpt.com
Developer commands · learn.chatgpt.com
Non-interactive mode · learn.chatgpt.com