Codex CLI MCP: Setup + Best Servers (2026)
How to set up MCP servers in Codex CLI (config.toml), the best servers to connect, the STDIO vs remote question, and managing MCP context across agents.
Out of the box, Codex CLI reads your repo and runs commands in a sandbox. It does not know what’s in your Linear backlog, what Sentry flagged last night, or what the current Next.js API actually looks like. The Model Context Protocol (MCP) is how you close that gap, and Codex reads its MCP setup from a single config.toml file. This guide covers the exact config, the transport question that trips people up, which servers are worth wiring, and how to keep credentials sane once more than one engineer is involved.
What is MCP and why does it matter for Codex?
MCP is an open protocol that connects a model to external tools and context over a standard wire format. Before it existed, every coding agent shipped one-off integrations for GitHub, your database, and your tracker. After it, a compliant server can plug into a compliant client that shares its transport and auth method. Codex supports MCP in both the CLI and the IDE extension and shares a single configuration between them, so a server you add once works in either client.
On the wire, MCP encodes messages as JSON-RPC: a server exposes tools, and Codex calls them as the client. The payoff is specific. Hook up Context7 and Codex writes against real version-specific docs instead of guessing at API signatures for fast-moving libraries. Hook up the GitHub server, and it can open and review pull requests instead of just editing local files.
One thing to flag early: Codex may use the instructions an MCP server returns during initialization as server-wide guidance alongside that server’s tools. If you maintain a server, keep that guidance concise and self-contained. The official Codex MCP docs spell out the full behavior.
How to add an MCP server to Codex CLI (config.toml, codex mcp add)
Codex keeps MCP configuration in config.toml, by default at ~/.codex/config.toml. You can scope servers to a single repo with a project-local .codex/config.toml, which Codex only loads for projects you’ve marked as trusted, and add servers either through the codex mcp commands or by editing the file directly.
The fast path is the CLI. To add a local (STDIO) server, name it and pass the launch command after a – separator:
codex mcp add context7 -- npx -y @upstash/context7-mcp
That single line registers Context7, a free server for up-to-date developer docs. The codex mcp family covers the rest of the lifecycle too: list, get <name>, remove <name>, and login/logout for OAuth-capable HTTP servers. See the Codex CLI command reference for the full set; inside the TUI, type /mcp to see which servers are live in the current session.
For finer control, edit config.toml directly. Each server is a [mcp_servers.<name>] table. A STDIO server needs a command, with optional args, env, and cwd:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
Two timeouts are worth knowing because they cause silent failures: startup_timeout_sec defaults to 10 and tool_timeout_sec defaults to 60. A heavy server that takes 12 seconds to boot will look broken until you raise the startup window.
The STDIO-only limitation (and remote-server workarounds)
This is the part most older tutorials get wrong, so check the version you’re reading against. Early Codex builds only spoke STDIO: Codex launches the server as a local subprocess and talks to it over stdin and stdout, and anything that needed an HTTP endpoint had to be wrapped in a local proxy.
Current Codex CLI supports both. The docs list STDIO servers and Streamable HTTP servers, the latter with bearer-token and OAuth authentication, mirroring the MCP transport spec, which defines exactly two standard transports: stdio and Streamable HTTP. “STDIO-only” is now a historical footnote, not a live constraint.
To register a remote server, point at a URL instead of a command: codex mcp add takes a –url flag, mutually exclusive with the command form, plus –bearer-token-env-var for auth. In config.toml, a Streamable HTTP server uses url (required) and optional bearer_token_env_var and http_headers. Auth methods vary by server, though: Figma’s remote MCP server uses an interactive OAuth login (codex mcp login figma), not a bearer-token env var, so its config only needs a URL:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
Check each server’s own docs before copying an example wholesale.
One more wrinkle: the older HTTP+SSE transport was replaced by Streamable HTTP in the 2025 spec revision, and Server-Sent Events now live inside it as an optional streaming mode rather than a separate transport. A tutorial that has you configure a standalone SSE endpoint predates the current spec.
The best MCP servers to connect (docs, GitHub, databases, security)
A coding agent with the wrong servers is just more attack surface. These are the ones that earn their place for shipping software, drawn from our roundup of MCP servers for coding agents:
- GitHub for repo access: browsing code, reading and writing issues, and opening or reviewing pull requests. For any agent that ships code, this is the one you can’t skip.
- Context7 for documentation grounding. It pulls version-specific docs from source so Codex writes against the real current API instead of a stale training cutoff.
- A database server such as a Postgres MCP for schema work and analysis. Run it read-only unless you have a reason not to; a write-capable connection can drop or delete anything the connection string reaches, and even read-only access can expose production data, so use least-privilege accounts and query limits.
- Sentry for production triage, turning a stack trace into context the agent can act on when you ask it to fix an error.
Resist the urge to install everything. Every server adds tools to the context window and widens what a compromised tool can touch. Four well-scoped servers beat a dozen redundant ones.
Managing MCP credentials and security
The moment Codex can call real tools, a few habits keep that access from going sideways.
Keep secrets out of the file. Pull values from your environment with env_vars for STDIO servers, or bearer_token_env_var for Streamable HTTP servers, instead of pasting raw keys into config.toml, especially a project-local .codex/config.toml that could land in version control.
Scope tools, not just servers. Each server entry takes an enabled_tools allow list, a disabled_tools deny list, and a default_tools_approval_mode (auto runs tools without prompting; prompt and approve gate them). If a server can read and write but you only need read access, allow-list the read tools.
Trust the project before the project’s config. Codex loads a project-scoped .codex/config.toml only for trusted projects; mark a project untrusted and Codex skips its local config, hooks, and rules. That matters when you clone an unfamiliar repo carrying its own .codex directory.
Remote servers carry their own risks: the MCP spec requires Streamable HTTP servers to validate the Origin header against DNS rebinding, and recommends binding to localhost and authenticating every connection.
The risk no config flag fixes is prompt injection. Tool output containing user-authored text, like an issue body or a Slack message, can carry instructions the model treats as commands. Treat tool results as untrusted input, prefer OAuth and scoped tokens over plaintext keys, and pin the packages you launch with npx: npx -y fetches the latest version on every run, which isn’t what you want in a team config.
MCP across many agents and repos: connecting context at scale
Everything above is per-machine. One engineer with five servers in ~/.codex/config.toml is a productive setup. Fifty engineers with five servers each is configuration drift: different versions, scopes, and tokens scattered across files nobody reviews. The org-level problem isn’t one agent and its tools. It’s the same context wired consistently, with an audit trail, across every agent and every repo.
This is the layer we work at. We orchestrate coding agents across your repos and run each one in an isolated sandbox, so MCP gets wired once at the workspace level instead of on every laptop. Integration servers for GitHub, Linear, Sentry, and Postgres turn on automatically when you connect the matching integration, custom servers over STDIO, Streamable HTTP, or SSE drop in from settings, and you can self-host the whole thing inside your own VPC.
Because Codex is one of the harnesses we run, the same MCP context is available whether a task lands on Codex, Claude Code, or another agent: click “Connect Linear” once instead of asking every engineer to hand-edit the same five entries. For the patterns behind running many agents this way, see our guide to multi-agent orchestration.
Troubleshooting common MCP issues
When a server won’t show up under /mcp, the cause is usually one of a handful of things:
| Symptom | Likely cause | Fix |
|---|---|---|
| Server never starts | Boot time exceeds the 10-second startup_timeout_sec default | Raise the timeout, then confirm the launch command runs on its own in a terminal |
| Tool calls time out | A long-running tool blows past the 60-second tool_timeout_sec default | Bump tool_timeout_sec for servers that do real work |
| Config silently ignored | CLI flags, then project config, then a profile, then your user config, override in that order | Check whether a project file or an untrusted project is overriding the value in ~/.codex/config.toml |
| Auth fails on a remote server | The OAuth login may not have completed, or the token env var isn't set | Run codex mcp login <name>, and confirm the referenced bearer_token_env_var is set in the shell that launches Codex |
If you need Codex to behave as a server rather than a client, that’s a different mode: codex mcp-server runs Codex itself as an MCP server over STDIO so another agent can call it. Useful, but not what most “my server won’t connect” problems are about.
Connecting Codex to the rest of your stack
MCP turns Codex from a smart local editor into an agent that can reach your real tools. The setup is small: one config.toml, a tight set of servers, and credentials kept in the environment. The harder problem shows up at team scale, where the same wiring has to stay consistent across many agents and repos.
If that’s where you are, we wire MCP once at the workspace layer and run Codex and any other agent against it, in our cloud or self-hosted in your own VPC. Start free with 10 free credits, a one-time grant on one repository with the option to top up anytime, and dispatch your first agent against your repos.
FAQ
Where does Codex CLI store MCP servers? In config.toml, by default at ~/.codex/config.toml, or a project-scoped .codex/config.toml for trusted projects. The CLI and IDE extension share the same file.
How do I add an MCP server to Codex CLI? Run codex mcp add <name>–<command> for a local server, or codex mcp add <name>–url<address> for a remote one, or edit config.toml directly with an [mcp_servers.<name>] table.
Does Codex CLI support remote MCP servers? Yes, both STDIO and Streamable HTTP, the latter with bearer-token and OAuth authentication. The STDIO-only restriction applied to older builds.
How do I list or remove a configured server? Use codex mcp list to see them, codex mcp get <name> to inspect one, and codex mcp remove <name> to delete it.
What’s the difference between STDIO and Streamable HTTP? STDIO runs the server as a local subprocess over stdin/stdout; Streamable HTTP reaches a server at an address over HTTP. The MCP spec defines these as the two standard transports.
Run any coding agent in the cloud
Tembo agents execute tasks in secure cloud environments and return reviewable output. Use any agent or model, run in parallel, and keep humans in control.
