Codex MCP: How to Add an MCP Server to Codex

Codex uses MCP (Model Context Protocol) servers to reach tools outside your repository: documentation, a browser, Figma, a publishing tool. You add a server once and the Codex CLI, the IDE extension and the ChatGPT desktop app all use it, because they read the same configuration.

The short version: run codex mcp add <name> -- <command> for a local server, or codex mcp add <name> --url <url> for a remote one, then codex mcp login <name> if it uses OAuth. Codex writes the server to ~/.codex/config.toml, where you can also edit it by hand. Type /mcp in Codex to see which servers are running. Everything below is from OpenAI's Codex MCP documentation, checked October 22, 2026.

What is MCP in Codex?

An MCP server exposes a few named tools; Codex decides when to call them while it works, the same way it runs shell commands. Codex supports two kinds of server:

• STDIO: a local process Codex starts with a command, such as an npx package.
• Streamable HTTP: a server you reach at a URL, often run by the service itself and signed into with OAuth.

How do I add an MCP server to Codex?

For a local server, put the command after --. This adds Context7, a documentation server:

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

Pass environment variables with --env, for example --env API_KEY=..., before the --. For a remote server, give its URL instead of a command:

codex mcp add skryvo --url https://api.skryvo.ai/mcp

Then check it with codex mcp list, and run codex mcp --help for every MCP subcommand your version has.

How do I set up MCP servers in config.toml?

Each server is a [mcp_servers.<name>] table in ~/.codex/config.toml. A project can also have its own .codex/config.toml, which Codex reads only for trusted projects. These three entries are adapted from OpenAI's examples:

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

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"

A local server needs command; args, env, env_vars and cwd are optional. A remote server needs url, and can take bearer_token_env_var or http_headers when it uses a static token instead of OAuth.

How do I sign in to a remote MCP server in Codex?

Run codex mcp login <name>. Codex opens the service's sign-in page, and the service shows its own consent screen. Codex registers itself with the server by Client ID Metadata Document when the server supports it, otherwise by Dynamic Client Registration; add --oauth-client-registration cimd or dcr to choose. If a server gave you a client ID already, pass --oauth-client-id when you add it and Codex skips registration. Servers that use a fixed token instead take it from an environment variable named in bearer_token_env_var, so the token never sits in the file.

Do the Codex CLI, IDE extension and app share MCP servers?

Yes. The Codex CLI, the IDE extension and the ChatGPT desktop app read the same MCP configuration, so a server added in one is there in the others. Type /mcp in the Codex terminal or in the desktop app's composer to list the connected servers. ChatGPT on the web is the exception: it does not read local Codex files and uses MCP tools through plugins instead, which our ChatGPT setup page walks through.

How do I control which MCP tools Codex can run?

• enabled_tools is an allow list; disabled_tools is a deny list applied after it.
• default_tools_approval_mode sets when Codex asks before calling a tool: auto, prompt, writes (asks only for tools not marked read-only) or approve.
• tools.<tool>.approval_mode overrides that for one tool, and tools.<tool>.output_token_limit caps how much of its output enters the conversation.

For any server that can change something outside your machine, such as posting, sending or deleting, writes is a sensible default: reads run freely and every write waits for you.

Why is my MCP server not working in Codex?

• It is slow to start. Codex waits 10 seconds by default. A first npx run that downloads a package can take longer; raise startup_timeout_sec.
• A tool call times out. The default is 60 seconds; raise tool_timeout_sec for slow tools.
• It fails silently. Set required = true on a server Codex should not run without, and startup will stop with an error instead.
• The project config is ignored. .codex/config.toml is read only in trusted projects.
• It works in the CLI but not on the web. ChatGPT on the web does not read Codex's config at all.

Run /mcp after each change to confirm the server is listed.

Can you run Codex as an MCP server?

Not any more. OpenAI's documentation now says the codex mcp-server command and the standalone codex-mcp-server binary have been removed, so guides that show Codex being called from Claude Code or the Agents SDK as an MCP server describe something that no longer ships. codex mcp now only manages the servers Codex connects to.

A worked example: posting from Codex

Skryvo is a remote MCP server for social media, so it shows the whole remote flow:

codex mcp add skryvo --url https://api.skryvo.ai/mcp
codex mcp login skryvo

After signing in, ask Codex "Draft an X thread about the bug we just fixed and schedule it for tomorrow at 9am." It drafts the thread in your brand's voice, shows it, and schedules it only after you agree; the Codex setup page has the details. The same server works in Claude, where it is a connector (see how to add Claude connectors), and in Cursor and other agents listed on the agents page.

Start with one server you will use every day, keep its approval mode on writes for a week, and widen it only for the tools you have watched work.