The quick path to add a Codex MCP server is a [mcp_servers.<name>] table, an OAuth login for a remote server that supports it, then a tool check in Codex. Use a stdio command for a local process or url for a Streamable HTTP endpoint.

Codex MCP connects the Codex CLI to tools exposed by local or remote Model Context Protocol servers. This guide follows OpenAI’s rolling Codex documentation checked November 7, 2026; the page does not pin these settings to one CLI release, so check codex --version and codex mcp --help before copying a command into an older install.

What does codex mcp configure?

codex mcp manages external MCP server entries; each entry is either a local stdio process or a remote Streamable HTTP endpoint. The current Codex MCP guide and OpenAI Codex CLI source document the setup flow, but the docs are rolling, not tied to a numbered CLI release.

codex mcp list is a configuration listing; it does not by itself prove that a server authenticated or returned usable tools.

The current CLI source defines six subcommands: add and remove change entries; list and get inspect them; login and logout manage OAuth credentials. list and get also support --json.

How do I add a local stdio or remote HTTP MCP server in Codex?

Use codex mcp add <name> -- <command> for stdio and codex mcp add <name> --url <URL> for Streamable HTTP. The double dash marks where the local server command begins.

The stdio syntax and Context7 command below are copied from the Codex MCP guide; these are documentation examples and were not run here:

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

For a TOML entry, use command with optional args, env, env_vars, and cwd. For HTTP, use url; Codex can use OAuth, a bearer token from an environment variable, or configured headers. Don’t put a token value directly in config.toml.

We make Unsame, and its Codex CLI setup uses two remote OAuth servers. Add these tables to ~/.codex/config.toml (the URLs are Unsame’s production endpoints):

toml
[mcp_servers.unsame_engine]
url = "https://api.unsame.io/mcp/engine"

[mcp_servers.unsame_author]
url = "https://api.unsame.io/mcp/author"

The engine server advises before writing and accepts outcome reports; author edits playbooks from chat. Unsame’s connect docs cover other supported apps. If you need backend integration instead of an MCP client, see the HTTP API docs.

Which codex config.toml keys matter for MCP?

OpenAI documented these common server keys on November 7, 2026. Their configuration reference is rolling and does not name a CLI release, so verify the installed CLI before relying on any field.

KeyUseApplies to
command, argsLaunch command and arguments.stdio
env, env_vars, cwdPass environment values, allow selected environment variables through, and set the process working directory.stdio
urlSet the server endpoint.Streamable HTTP
bearer_token_env_varName the environment variable containing a bearer token.Streamable HTTP
oauth_resourceSupply the RFC 8707 resource value during OAuth login when the server requires it.Streamable HTTP
http_headers, env_http_headersSend static headers or headers whose values come from environment variables.Streamable HTTP
startup_timeout_sec, tool_timeout_secSet startup and per-tool timeouts; documented defaults are 10 seconds and 60 seconds.Both
enabledSet false to keep an entry while disabling it.Both
enabled_tools, disabled_toolsAllow-list tools, then remove any denied tools.Both

The docs also list other controls, including OAuth scopes and callback settings. Don’t add a key from an old snippet unless the current reference lists it. For an HTTP endpoint with OAuth, url is enough to configure the server; start login separately when needed.

How do I log in to a remote OAuth MCP server with codex mcp login?

Run codex mcp login <server-name> and finish the provider’s browser flow. If the terminal cannot open a browser, the Codex MCP guide documents --no-browser; it prints a URL for you to open elsewhere and asks you to paste the full redirect URL back.

For Unsame, log in once for each configured server. These command forms follow Codex’s documented codex mcp login <server-name> command and Unsame’s documented server names; they are shown for the end-to-end example and were not run in this draft:

sh
codex mcp login unsame_engine
codex mcp login unsame_author

Then check the list and start a new Codex session. A successful login does not always reach a thread that was already open: an open Codex issue (Windows, Codex 0.130.0, June 2026) reports a Desktop thread that kept failing with OAuth authorization required after codex mcp login succeeded, until a restart or new session.

How can I verify Codex loaded the MCP server's tools?

Start with codex mcp list to see the configured servers, then run /mcp in the Codex TUI to see the active ones; the official guide documents both. In current versions codex mcp list also prints each server’s auth status (CLI source). Then make a real tool call: it’s the only check that the session can use the tools.

For Unsame, ask Codex to list your goals using the goal_list tool. If it can list them, the remote server is reachable and that tool is available in the session. We tested Codex CLI end to end against Unsame; this example is the extent of our product-specific verification claim.

What should I check when a Codex MCP server fails?

Match the symptom to its layer before changing the config. These reports come from specific GitHub issues and versions; use them as failure patterns, not proof that every Codex install has the same bug.

SymptomCheck and fixEvidence
Stdio server fails with No such file or directory or times out at startup.Run the command yourself, then check the command path and the PATH Codex inherited. An open Codex issue reports bare executable names failing when a GUI-launched Codex process lacks the login-shell PATH; its workaround is to put the executable’s absolute path in command. If the process starts but initializes slowly, raise startup_timeout_sec from its documented 10-second default.Issue #58004; Codex config reference
OAuth login fails, or the server rejects the token with 401.On a machine without a browser, add --no-browser to the login command; Codex shows a URL to open on another device, and you paste the redirect URL you land on back into the terminal. If login succeeds but the MCP server rejects the token for a resource-audience mismatch, set oauth_resource to the server’s protected resource URL and log in again; issue #24890 was closed after the reporter identified this missing parameter. If an already-open Desktop thread keeps returning OAuth authorization required after login, restart Codex or start a new session; issue #29279 is still open for this.Codex MCP guide; config reference; issue #24890; issue #29279
Server appears but expected tools do not.Check that enabled is not false; inspect enabled_tools and disabled_tools, since the deny list applies after the allow list. Then use /mcp and attempt a tool call. A Codex issue from CLI 0.128.0 reports a server completing its handshake while its tools were not exposed to the model, so a visible server is not conclusive proof of tool availability.Codex config reference; issue #20771
CLI works but the IDE extension has no MCP tools.In the extension, open the gear menu → MCP servers, add or inspect the server, save, then select Restart extension. A VS Code extension issue records this mismatch on CLI v0.56.0; a commenter there suggests comparing CODEX_HOME, the selected project, and the environment the extension sees. That is a community suggestion, not a documented fix.Codex MCP guide; issue #6465

For issues that persist, record Codex version, OS, transport, exact error, and whether the failure happens in CLI, TUI, or extension; don’t include credentials.

What if I’m setting up Claude instead?

Claude’s setup uses a different client workflow; see our guide to Claude connectors or the connection docs.

Try Unsame from Codex

After both Unsame servers are authenticated, ask Codex to call goal_list; then choose a goal and scope before asking it to use the engine. Unsame returns a writing protocol, while your model writes the text. You can create an account to set up a playbook.

— Don