# Codex MCP: Add Servers, Sign In, Fix Errors

> Codex MCP server setup with current config.toml keys, stdio and remote HTTP examples, codex mcp login for OAuth, verification steps, and common fixes.

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](https://developers.openai.com/codex/mcp) and [OpenAI Codex CLI source](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs) 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](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs) 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](https://developers.openai.com/codex/mcp); 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](/docs#connect) cover other supported apps. If you need backend integration instead of an MCP client, see the [HTTP API docs](/docs#http-api).

## Which `codex config.toml` keys matter for MCP?

OpenAI documented these common server keys on November 7, 2026. Their [configuration reference](https://developers.openai.com/codex/config-reference) is rolling and does not name a CLI release, so verify the installed CLI before relying on any field.

| Key | Use | Applies to |
| --- | --- | --- |
| `command`, `args` | Launch command and arguments. | stdio |
| `env`, `env_vars`, `cwd` | Pass environment values, allow selected environment variables through, and set the process working directory. | stdio |
| `url` | Set the server endpoint. | Streamable HTTP |
| `bearer_token_env_var` | Name the environment variable containing a bearer token. | Streamable HTTP |
| `oauth_resource` | Supply the RFC 8707 resource value during OAuth login when the server requires it. | Streamable HTTP |
| `http_headers`, `env_http_headers` | Send static headers or headers whose values come from environment variables. | Streamable HTTP |
| `startup_timeout_sec`, `tool_timeout_sec` | Set startup and per-tool timeouts; documented defaults are 10 seconds and 60 seconds. | Both |
| `enabled` | Set `false` to keep an entry while disabling it. | Both |
| `enabled_tools`, `disabled_tools` | Allow-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](https://developers.openai.com/codex/config-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](https://developers.openai.com/codex/mcp) 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](https://github.com/openai/codex/issues/29279) (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](https://developers.openai.com/codex/mcp) documents both. In current versions `codex mcp list` also prints each server’s auth status ([CLI source](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs)). 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.

| Symptom | Check and fix | Evidence |
| --- | --- | --- |
| 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](https://github.com/openai/codex/issues/58004) 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](https://github.com/openai/codex/issues/58004); [Codex config reference](https://developers.openai.com/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](https://github.com/openai/codex/issues/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](https://github.com/openai/codex/issues/29279) is still open for this. | [Codex MCP guide](https://developers.openai.com/codex/mcp); [config reference](https://developers.openai.com/codex/config-reference); [issue #24890](https://github.com/openai/codex/issues/24890); [issue #29279](https://github.com/openai/codex/issues/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](https://github.com/openai/codex/issues/20771) 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](https://developers.openai.com/codex/config-reference); [issue #20771](https://github.com/openai/codex/issues/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](https://github.com/openai/codex/issues/6465) 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](https://developers.openai.com/codex/mcp); [issue #6465](https://github.com/openai/codex/issues/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](/blog/claude-connectors) or the [connection docs](/docs#connect).

## 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](/login?next=/app) to set up a playbook.

— Don
