GuidesRunning & maintaining

Codex MCP servers: codex mcp add, config.toml and OAuth

Add an MCP server to Codex CLI with codex mcp add or config.toml, sign in with OAuth on a server with no browser, and why codex mcp-server is gone.

November 21, 2026The Everpod team
The short answer

Add a server with codex mcp add: the command that starts a local server goes after --, a remote server takes --url. Either way the entry lands under [mcp_servers.<name>] in ~/.codex/config.toml, which you can also edit by hand. codex mcp list, get and remove manage entries, codex mcp login signs in to a server that uses OAuth (add --no-browser over SSH), and /mcp inside a session shows what connected. A local server does not see your shell’s variables unless you pass them. And codex mcp-server, which ran Codex itself as an MCP server, is gone. This is Codex CLI 0.171.0, as of November 2026.

# a local server, started by Codex over stdio
codex mcp add context7 -- npx -y @upstash/context7-mcp

# a local server that needs a variable
codex mcp add myserver --env LOG_LEVEL=info -- my-mcp-command

# a remote server over streamable HTTP, key read from a variable
codex mcp add name --url https://api.example.com/mcp \
  --bearer-token-env-var MY_KEY

codex mcp list                      # what is configured
codex mcp get name                  # one entry (--json for JSON)
codex mcp login name --no-browser   # OAuth sign-in without a browser
codex mcp logout name               # forget the sign-in
codex mcp remove name               # delete the entry
Copied

The six commands

On 0.171.0, codex mcp has list, get, add, remove, login and logout. add takes a name and exactly one transport: a command after -- or --url, never both. It writes to your user config, and says so: Added global MCP server 'name'. There is no option to write a project’s config instead; for that, edit .codex/config.toml in the project yourself, which Codex reads only in a project you have trusted.

codex mcp list prints two tables, local servers with their command, arguments, variables and working folder, remote ones with their URL and bearer variable, each with a status and auth column. list and get both take --json. Neither starts a session, so a server that will fail to start still lists fine; the connection is tried when a session starts.

The config.toml entry

Everything add does can be written by hand. A local server, in the shape OpenAI’s MCP page uses:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { LOG_LEVEL = "info" }
env_vars = ["CONTEXT7_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.name]
url = "https://api.example.com/mcp"
bearer_token_env_var = "MY_KEY"
enabled_tools = ["search", "fetch"]
Copied

The keys the configuration reference documents for a server:

Anything in env or http_headers sits in the file in clear; a key belongs in a variable named by env_vars, bearer_token_env_var or env_http_headers. The rest of the file’s settings are in the guide to Codex’s config.toml.

What a local server sees on the machine

A local server is a child process of Codex, run as your user, in its own process group, which Codex ends when the session closes. It does not get Codex’s whole environment. In the 0.171.0 source, Codex clears the child’s environment and passes only a short list, when set: HOME, LOGNAME, PATH, SHELL, USER, LANG, LC_ALL, TERM, TMPDIR and TZ, plus whatever env_vars names and env sets. The docs say as much in fewer words, calling env_vars variables “to allow and forward.”

So an API key you exported in your shell, or in the tmux session you run Codex in on a server, reaches Codex and stops there. A server that starts and then fails on a missing key usually needs that variable’s name in env_vars. The PATH it gets is Codex’s, so a command such as npx installed under a version manager is found only if Codex itself was started from a shell that had it; giving the full path in command removes the doubt.

Remote servers, keys and OAuth

A remote server is streamable HTTP; the docs list no other remote transport. When it takes a key, the key stays in a variable and only the variable’s name goes in the file; how that compares with Claude Code, which writes the header itself, and what each prints when the key is wrong, is in connecting Claude Code and Codex to a remote MCP server.

When it uses OAuth, add finds out by itself: it saves the entry, prints Detected OAuth support. Starting OAuth flow… and tries to open a browser. When it cannot tell, it prints a line telling you to run codex mcp login name. Codex waits up to five minutes for the sign-in to return to a listener it opens on 127.0.0.1 of the machine Codex runs on.

On a server with no browser, that listener is the problem: the browser on your laptop cannot reach it. The documented route is:

codex mcp login name --no-browser
Copied

Codex prints the authorization URL; open it on your own machine, sign in, and paste the full URL the browser lands on (a page that fails to load) back into the terminal. Over SSH, connect with an interactive terminal so the paste prompt works. If you ran add first and its sign-in is waiting on a browser that will never open, the entry is already saved: stop it and run the command above. --scopes asks for particular scopes, and codex mcp logout name removes the stored credentials. Where they are stored is the top-level mcp_oauth_credentials_store setting, with auto, file or keyring. A server whose client is registered with a fixed callback takes mcp_oauth_callback_port or mcp_oauth_callback_url, and the callback you register has to match the one add prints.

Checking it inside a session

/mcp in the Codex TUI lists the servers and their tools; /mcp verbose adds diagnostics, and /mcp login name signs in from inside the session. A server missing there, while codex mcp list shows it, failed at startup: the usual causes are a command not on the PATH Codex passes, a variable not forwarded, or a server slower than the 10-second startup timeout, which startup_timeout_sec raises. Setting up Codex itself on a remote machine is the Codex CLI on a Linux server.

Codex as an MCP server

Older guides show codex mcp-server, which let another agent call Codex as a tool over MCP. OpenAI’s removal notice says “The codex mcp-server command and the standalone codex-mcp-server binary have been removed,” and 0.171.0 has no such command. The replacement it points to, the app server, speaks its own protocol and “isn’t an MCP server or a drop-in replacement for an MCP client,” and is experimental. An integration built on codex mcp-server keeps working only on a Codex old enough to have it; connecting Codex to other MCP servers, everything above, is unaffected. What an MCP server is in the first place is in what an MCP server is.

Run Codex on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.