Codex MCP Servers: Config, Transports, and What Works
Codex reads MCP servers from ~/.codex/config.toml (or a project-scoped .codex/config.toml), supports both stdio and streamable HTTP transports, and manages the whole lifecycle from a codex mcp subcommand family — but it implements only the tools part of the MCP spec, and the surfaces that read your config are narrower than you’d guess. This page is the working reference: exact config keys, the transport decision, the OAuth flow, the spec gaps that cause the most confusing failures, and which servers are worth wiring up.
If you’re new to the protocol, What Is MCP? covers it in a sentence, and MCP Servers: The Complete List is the parent map of every app with a server today. This page is the Codex-specific layer on top of it.
Where Codex looks for MCP config
Codex keeps MCP servers in the same TOML file as everything else — one table per server, keyed [mcp_servers.<name>]:
- User-level:
~/.codex/config.toml— your personal servers, available in every project. - Project-level:
.codex/config.toml— checked into the repo so the team shares the same servers. Loaded only from trusted directories, which is the single most common reason a committed project config appears to do nothing.
The two merge, with user-level config winning on conflicts.
The transport is chosen implicitly by which keys are present. A command key means stdio. A url key means streamable HTTP. There is no type or transport field to set, and supplying both is a configuration error rather than a fallback chain.
stdio servers
A local child process Codex launches and speaks to over stdin/stdout:
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]
env = { PLAYWRIGHT_BROWSERS_PATH = "0" }
startup_timeout_sec = 20Keys that apply to stdio servers: command (the launcher), args, env (variables handed to the server process), env_vars (an allowlist of variables forwarded from your shell rather than hardcoded), and cwd (working directory). Use env_vars rather than env for anything secret — it keeps the value out of the file.
Streamable HTTP servers
A remote endpoint Codex calls over HTTPS. This is the transport most vendor-hosted servers ship today:
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"Authentication has three shapes, in rough order of how often you’ll want them:
- OAuth — the default (
auth = "oauth"). Runcodex mcp login linearand Codex discovers the authorization server via/.well-known/oauth-authorization-server, opens a browser, catches the callback on a local port, and stores the tokens outsideconfig.toml— Keychain on macOS, encrypted file storage on Linux. Refresh happens without re-prompting. - Bearer token from the environment —
bearer_token_env_var = "LINEAR_TOKEN". Codex reads the variable at connect time and sends it asAuthorization: Bearer …. - Raw headers —
http_headersfor static values,env_http_headersfor header values pulled from environment variables. This is the escape hatch for servers using a non-standard scheme.
There’s also auth = "chatgpt" for trusted first-party servers, which reuses your existing Codex session instead of running a separate OAuth dance.
The codex mcp subcommands
Since March 2026 the CLI has managed servers end to end, so hand-editing TOML is optional:
| Command | What it does |
|---|---|
codex mcp add <name> | Register a server. stdio takes a -- separated command; HTTP takes --url. |
codex mcp list | List every configured server with its auth status |
codex mcp get <name> | Print the resolved config for one server |
codex mcp remove <name> | Delete the entry |
codex mcp login <name> | Run the OAuth flow |
codex mcp logout <name> | Clear stored credentials |
In practice:
# stdio — everything after `--` is the server command
codex mcp add playwright --env PLAYWRIGHT_BROWSERS_PATH=0 -- npx -y @playwright/mcp@latest
# streamable HTTP with a bearer token
codex mcp add linear --url https://mcp.linear.app/mcp --bearer-token-env-var LINEAR_TOKENWrites are atomic, so a failed add won’t leave you with a half-written config. Two gaps worth knowing: there’s no enable/disable subcommand yet (you flip the enabled key by hand), and codex mcp add can’t set an oauth_resource indicator, which some enterprise-gated servers require — those still need a manual TOML edit.
What Codex implements from the MCP spec — and what it drops
This is where most “the server is configured but Codex can’t see it” reports come from. Codex implements tools. It does not implement resources, prompts, or sampling.
That’s a defensible scope for a coding agent — tools are the part that does work. The problem is the discovery path. Codex has leaned on resources/list when deciding whether a server is available, so a perfectly healthy tools-only server returns an empty resource list and Codex reports it as unavailable or not installed, even while /mcp shows it connected. Context7 and similar tool-only servers have hit this repeatedly. If a server looks connected but Codex insists it has no MCP access, this is almost certainly what you’re seeing — not a broken config.
The practical consequence: a server whose value is its prompt library gives you nothing in Codex. Only the tools come through.
Config keys that change behavior, not just plumbing
Most of the leverage in a Codex MCP setup is in these, not in the connection itself:
startup_timeout_sec(default 10) andtool_timeout_sec(default 60). Servers that compile on first run, or tools that do long queries, need these raised. A server that “randomly fails to load” is usually a 10-second startup budget.enabled_toolsanddisabled_tools. An allowlist applied first, then a denylist. Every tool a server exposes costs context on every turn, so a 40-tool server you use three tools from is worth trimming aggressively.default_tools_approval_mode—auto,prompt,writes, orapprove— with per-tool overrides via[mcp_servers.<name>.tools.<tool>]. The pattern that holds up: reads auto-approved, writes gated.required = truefails Codex startup if that server can’t initialize. Useful in CI, hostile on a laptop.enabled = falseparks a server without deleting it.experimental_environmentplacement, andsource = "remote"for secrets read from a remote executor environment — relevant if you’re runningcodex cloud exec.
Organizations can constrain all of this centrally through a requirements.toml that allowlists server URLs or bans stdio servers outright, in which case a non-compliant config silently falls back rather than connecting.
Which surface actually reads your MCP config
Not all of them, and this catches people out:
- Codex CLI — full support. This is the reference implementation.
- IDE extension and the ChatGPT desktop app — share the same MCP configuration for the same Codex host. Detection has been less reliable than the CLI, and a server that works in the terminal but not in the editor is a known failure mode rather than a config error on your side. Restarting the extension host after a config change is the usual fix.
- Codex cloud — no native MCP configuration from environment settings. This is an open feature request, not a shipped feature. Cloud tasks don’t inherit the servers on your laptop.
- ChatGPT web — uses remote MCP-backed tools through installed apps. It never reads your local Codex config.
So “add an MCP server to Codex” means, in practice, “add it to the surfaces running on your machine.”
Plugins: MCP servers with the config already written
Since the March 2026 plugin marketplace, a lot of MCP setup is now packaged. A Codex plugin is a bundle that can carry skills, app connectors, hooks, and an .mcp.json that configures MCP servers — so installing a plugin can wire a server without you touching TOML.
/plugins # browse and install from the CLI
codex plugin marketplace add <owner/repo>
codex plugin add <plugin-name>Marketplace sources support version pinning with @branch or #tag. Plugins work across the desktop app, CLI, and VS Code extension, and OpenAI has shipped partner plugins covering Slack, Figma, Notion, Sentry, GitLab, CircleCI, Atlassian, and Render among others. If a vendor you want has a plugin, it’s a shorter path than a hand-written server entry — and the MCP config inside it is readable, so you can see exactly what got added.
Servers worth wiring into Codex
Codex is a coding agent, so the highest-value servers are the ones that put the rest of your engineering surface in reach without a context switch. We have per-app breakdowns for the ones Codex users add most:
Code hosting & CI GitHub · GitLab · Bitbucket · CircleCI
Issues & planning Linear · Jira · Notion · Slack · Jira · Linear · Shortcut
Observability & incidents Sentry · Datadog · Grafana
Infra & deploys Vercel · Cloudflare · Supabase · Postman
Mail & calendar Gmail · Outlook · Google Calendar · Outlook Calendar
Because MCP is client-agnostic, any server in the wider ecosystem works in Codex as long as it exposes tools. The ones outside the developer stack are worth knowing about if you’re wiring Codex into ops work:
Docs & knowledge Notion · Confluence · Google Docs · Google Sheets · Google Drive · Airtable · Coda · Contentful
Messaging & meetings Slack · Microsoft Teams · Discord · Telegram · Zoom
Project & task tracking Asana · ClickUp · Monday · Trello · Todoist · Wrike · Basecamp · TickTick
Support & on-call PagerDuty · Zendesk · Intercom · Freshdesk · Freshservice
Payments & billing Stripe · Square · Shopify · QuickBooks · Xero · Brex
CRM Salesforce · HubSpot · Pipedrive · Attio · Apollo · Gong · Customer.io
Analytics & marketing Google Analytics · Google Search Console · Semrush · Ahrefs · Google Ads · Meta Ads · Apify · SendGrid · Resend
Files, design & the rest Dropbox · Box · SharePoint · Canva · Adobe · Miro · Webflow · Typeform · LinkedIn · YouTube · Figma · WooCommerce · Amazon
The full grouped list lives on MCP Servers, and How to Install an MCP Server covers the generic setup path across clients. Comparing agents rather than servers? OpenAI Codex Alternatives and ChatGPT MCP cover the neighboring clients.
Vendor /mcp pages are not shipped servers
One habit worth keeping while you assemble a server list: a marketing page at vendor.com/mcp is not proof a server exists. Plenty of them describe roadmap intent, an internal beta, or a partner-gated endpoint you can’t reach with an ordinary account. Before you commit a server to a shared .codex/config.toml, confirm there’s a real endpoint or a published package — an npm package name, a GitHub repo, or a documented HTTPS URL that survives codex mcp login. A url pointing at a page that 404s on the MCP handshake fails at startup, and with required = true it takes the whole session with it.
The thing MCP doesn’t fix, no matter how many servers you add
Wire up twenty servers and Codex still does exactly nothing until you type. That’s not a Codex limitation — it’s the protocol.
MCP servers wait to be asked. The protocol has no scheduler and no event mechanism — its maintainers acknowledge that change detection today means polling — so an MCP connection can answer a question but cannot notice something on its own.
Which is fine for the job Codex has. You’re at the keyboard; the agent reaching into Sentry and Linear mid-task is the whole point. But it means the class of work that isn’t keyboard-adjacent stays manual: the deploy that should have posted to Slack, the overdue invoice that should have chased itself, the form submission that should have created the ticket. Nothing on the MCP side is watching.
The unattended-work gap closed in 2026: ChatGPT Scheduled Tasks and Claude Cowork both run on their own. The remaining gap is what starts them. These run on a timer, not in response to an event in your apps, so "when this happens, do that" is still outside what they do.
If that’s the gap you’re actually trying to close, an MCP server is the wrong shape and no amount of config tuning changes it — you need an automation layer with event triggers. Carly is one: it connects natively to ~260 apps and to anything else with a public API through your own key, and its workflows fire on events and schedules rather than on you typing. It’s free for unlimited Zapier-style workflows, with AI agents from $35/month. It doesn’t replace Codex — it covers the half of the work that never starts with a prompt.
FAQ
Where is the Codex MCP config file?
~/.codex/config.toml for user-level servers, or .codex/config.toml in a repo for project-scoped ones. Project config only loads from trusted directories, and user config wins where the two conflict. Servers go in [mcp_servers.<name>] tables.
Does Codex support remote MCP servers?
Yes — streamable HTTP, with OAuth (codex mcp login <name>), bearer tokens from environment variables, or custom headers. Add url instead of command and Codex picks the HTTP transport automatically. There’s no separate transport field.
Why does Codex say it has no MCP access when my server is configured?
Most often because the server exposes tools but no resources. Codex has used resources/list in its availability check, so a tools-only server can come back empty and get reported as unavailable even though it’s connected and its tools work. Check /mcp — if the server is listed there, try calling a tool directly rather than trusting the availability message.
Do MCP servers work in Codex cloud? No. Codex cloud has no native MCP configuration from environment settings — it’s an open feature request. MCP works in the CLI, the IDE extension, and the desktop app, all of which read the config on your machine.
Does Codex support MCP prompts and resources? Tools only. Prompts, resources, and sampling are not implemented, so a server whose main offering is a prompt library contributes nothing in Codex.
Can an MCP server in Codex run something on its own? No. MCP has no trigger mechanism and no scheduler — servers respond to requests inside a session and nothing else. Anything that needs to start on an event or a schedule needs an automation layer sitting outside the protocol.
Ready to automate your busywork?
Carly schedules, researches, and briefs you—so you can focus on what matters.
See what people say
"Before Carly, I relied on a Calendly link, but the whole process felt impersonal and not very professional. Carly changed that by handling all the back-and-forth, so I'm no longer stuck in endless email threads trying to line up schedules.
Now Carly reaches out to candidates, shares my real-time availability, lets them pick a slot, then sends a Zoom link and drops it straight into my calendar. She sends reminders to both of us before each call, which has significantly reduced no-shows and last-minute confusion.
On top of scheduling, Carly acts like a full executive assistant, sending me my schedule the night before so I can prepare for each call. It reminds me of the old x.ai assistant, but Carly is noticeably smarter, faster, and better suited to my healthcare recruitment business."
