How to Connect Your First MCP Server in Codex (2026)

- The commands, flags, and config.toml syntax below were cross-checked against the official docs at learn.chatgpt.com/codex/extend/mcp at the time of writing (08/2026); the Codex CLI moves faster than the docs, so run codex mcp add --help to check your installed version before you depend on any of this.

What "connecting an MCP server" means in Codex

MCP (Model Context Protocol) is an open standard that lets an agent call external tools/data through one shared interface instead of a one-off integration per tool. In Codex, "connecting an MCP server" means telling Codex which command (or URL) launches the server, plus any environment variables or tokens it needs to run.

The first thing to remember: Codex only acts as an MCP client - it calls out to external servers, it doesn't turn into an MCP server that other tools call into. No documentation confirms a server mode for Codex. If you're still new to MCP as a concept (not Codex-specific), start with what MCP is and how it works and come back here.

Three ways to add a server

Codex gives you three paths to add a server, none more "correct" than another - pick based on your workflow:

All three write to the same place: config.toml. Full reference lives at the official Codex MCP docs. The sections below cover the CLI and direct-edit methods in depth - the fastest two if you're already comfortable in a terminal.

Method 1 - add a server from the CLI (STDIO)

The core command has one shape:

codex mcp add <server-name> -- <server-launch-command>

A real example, straight from OpenAI's own docs - context7 (version-aware library/framework documentation lookup), run via npx:

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

I'm using this example instead of a commercial vendor's server because it's neutral - nobody's slipping their own product in as your first-run example. Most third-party Codex-MCP guides use their own server as the demo, which works, but it also means you're testing their product's happy path, not necessarily a clean baseline. If a server needs environment variables (API keys, tokens…), add them with the --env flag, repeated once per variable:

codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-server

After adding, verify two ways:

• codex mcp list - lists configured servers.
• Type /mcp inside a Codex TUI session - shows which servers are active in that session.

If the server doesn't show up, it's almost always a mistyped -- (the double-dash that separates codex mcp add's own flags from the server's actual command) - check that before assuming the server itself is broken.

Method 2 - edit config.toml directly

For more explicit control, or if you want to version-control MCP config alongside a project, edit the file directly. A STDIO server looks like this:

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

[mcp_servers.context7.env]
API_KEY = "your-value-here"

A Streamable HTTP (remote) server uses a different set of keys - url instead of command/args, for example a Figma server:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }

bearer_token_env_var points to the name of an environment variable holding the real token - you set that variable on your machine, you don't write the token straight into the file. ~/.codex/config.toml is the global file, applying to every project. For projects marked trusted, Codex also reads a .codex/config.toml file inside the project directory itself - useful if you want per-repo MCP config checked into version control.

Adding a remote (Streamable HTTP) server

The confirmed route for HTTP servers today is Desktop Settings or the IDE extension's gear menu: enter a name, pick STDIO or HTTP, paste the URL. This path is clearly documented.

Here's where to hedge: some third-party guides (not the official docs) show syntax like codex mcp add <name> --url <url> for adding an HTTP server straight from the CLI. OpenAI's official docs, at the time of writing, don't confirm this --url flag in the CLI syntax section. Don't assume it exists - run codex mcp add --help to check whether the exact CLI version you have installed supports it before you rely on it. Worst case, editing config.toml by hand (Method 2 above) works regardless of what your installed CLI version supports, since it doesn't depend on a specific flag existing.

A few fine-tuning keys apply to both STDIO and HTTP, declared inside the same [mcp_servers.<name>] block: startup_timeout_sec, tool_timeout_sec, enabled (turn the server on/off), and enabled_tools/disabled_tools (allow-list/deny-list which tools that server may expose).

Codex vs Claude Code - MCP config isn't the same

This site covers both Claude Code and Codex, so it's worth saying plainly: don't carry habits from one tool straight over to the other.

Want to see the same real server (GitHub) wired up on the other side? Read connecting the GitHub MCP server to Claude Code - a concrete cross-tool example, not theory.

Verify it worked

Fastest check: type /mcp in the TUI to see which servers are active in the current session. The most common failure modes:

• Missing environment variable - the server needs API_KEY but you forgot --env or the .env block in the TOML.
• Wrong command/args - a mistyped package name, or a missing -y when running through npx.
• HTTP token not set - the variable named by bearer_token_env_var was never set on your machine, so the server fails auth even with correct syntax.

One line to keep the boundary clear: an MCP server gives Codex new tools to call (read a Figma file, query a database…). AgentKit's skills layer (agentkit.best, paid kit - different from OpenAI AgentKit) is a separate layer on top, packaging prebuilt workflows - not the same thing as connecting an MCP server, and you don't need one to use the other.

Frequently asked questions (FAQ)

Is Codex an MCP server or only a client?

Only a client. Codex calls out to external MCP servers to get more tools/data; no documentation confirms Codex itself runs as an MCP server that other tools call into.

What's the exact command to add an MCP server?

codex mcp add <server-name> -- <launch-command>, for example codex mcp add context7 -- npx -y @upstash/context7-mcp. Add environment variables with --env KEY=VALUE, repeated per variable.

Where does Codex store MCP config?

At ~/.codex/config.toml (global, applies to every project), under [mcp_servers.<name>]. For trusted projects, Codex also reads a .codex/config.toml file inside the project directory.

What's the difference between STDIO and Streamable HTTP?

STDIO runs the server as a local process via command/args (for example, launched through npx). Streamable HTTP calls a remote server over url, authenticated with bearer_token_env_var or a custom header - nothing to install locally.

Can I add a remote server straight from the CLI?

Not confirmed. Some third-party guides show a --url flag, but Codex's official docs don't list it at the time of writing. The confirmed route today is Desktop Settings or the IDE gear menu; to check whether your CLI supports it, run codex mcp add --help.

Is Codex's MCP setup the same as Claude Code's?

No. Codex uses TOML (config.toml) with no explicit scope flag; Claude Code uses JSON (.mcp.json) with an explicit -s local/project/user flag. Same underlying MCP standard, different configuration mechanics - don't copy syntax straight from one tool to the other.

Conclusion

Pick the CLI for a fast STDIO add, Desktop/IDE when you need a remote HTTP server and aren't sure your CLI supports that flag yet, and edit config.toml directly when you want per-project config under version control. Looking to extend Codex beyond MCP? See Codex Skills (SKILL.md) - a parallel extension path, not a replacement for MCP. New to Codex overall? Start with what OpenAI Codex is.