Integration guide

How to connect any MCP server to OpenAI Codex CLI

Add a local MCP server to Codex CLI, confirm that it works, then connect the same tools through MCP Nest for remote and non-interactive use.

MCP Nest Team Published Updated

Codex CLI launches MCP servers as local subprocesses defined in ~/.codex/config.toml. That works until you want the same tools on a second machine, in a container, or in CI. Every one of those needs the packages installed, the API keys present, and the runtime available.

Pointing Codex at MCP Nest instead moves that whole problem off the machine. Your servers run in the cloud with their credentials, and Codex connects to one endpoint. Copying your config to a new laptop becomes copying five lines of TOML.

Add a local MCP server to Codex

Open or create ~/.codex/config.toml, then add one table for the server. For example, this configuration starts the Context7 MCP server with npx:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Replace context7, npx, and the arguments with the name and launch command for the server you want to use. After saving the file, restart Codex.

Run codex mcp list to confirm that Codex loaded the server. You can also start Codex and enter /mcp to see the active MCP servers.

This local setup is enough when you use Codex on one machine. The server and its runtime must be installed there, and any API keys it needs must be available in that machine’s environment.

Connect the same server through MCP Nest

You need a deployed MCP Nest config. See Getting Started with MCP Nest.

Find your connection URL

Open your config dashboard (for example https://mcpnest.dev/<YOUR_CONFIG_ID>/dashboard). The URLs are at the top of the page.

Authenticated URL Panel

There are two, and which you want depends on whether the machine has a browser:

  • Streamable HTTP Endpoint, on the OAuth (Claude, Cursor, etc.) tab: https://mcp.mcpnest.dev/mcp/<YOUR_CONFIG_ID>. Codex opens a browser to authorize on first use.
  • Authenticated URL: the same URL with ?token=... appended. No browser, no handshake. This is what you want on a server, in a container, or in CI.

Configure Codex

Codex speaks stdio to its MCP servers, so the connection goes through mcp-remote, which bridges stdio to a remote HTTP MCP endpoint.

  1. Open or create ~/.codex/config.toml.

  2. Add: 

[mcp_servers.mcpnest]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.mcpnest.dev/mcp/<YOUR_CONFIG_ID>"]

Replace <YOUR_CONFIG_ID> with the id from your dashboard.

  1. Start Codex. On first run it opens a browser for the OAuth flow; approve the connection and the tools become available.

Non-interactive setup

On a machine with no browser (a build agent, a remote box, a container), use the Authenticated URL and the handshake never happens:

[mcp_servers.mcpnest]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.mcpnest.dev/mcp/<YOUR_CONFIG_ID>?token=xxx"]

That token is a bearer credential for your whole config. Keep config.toml out of version control, or read the token from the environment if your setup allows it. Using MCP Nest without OAuth has the details.

Separate configs per project

Because a config id is just part of the URL, you can give each project the tools it needs and nothing else:

[mcp_servers.work]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.mcpnest.dev/mcp/<WORK_CONFIG_ID>"]

[mcp_servers.personal]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.mcpnest.dev/mcp/<PERSONAL_CONFIG_ID>"]

See deploying multiple separate configurations.

What the tools look like

MCP Nest namespaces every tool as <server>__<tool>, so a github server in your config appears as github__create_issue, github__list_pull_requests, and so on. With Codex the whole set arrives under the mcpnest entry from your TOML.

A long tool list eats context on every request and makes the model’s choice less reliable. Disable what a project doesn’t need from the MCP Nest dashboard. The toggles are per-user and drop tools out of tools/list without a redeploy. See how to disable individual MCP tools.

Troubleshooting

Codex starts but lists no tools. Run the mcp-remote command from your args by hand in a terminal. The connection error it prints is usually clear, and it is hidden when Codex runs it as a subprocess.

The server times out on startup. npx -y mcp-remote downloads the package on first use, which can outrun Codex’s startup timeout. Run npx -y mcp-remote --help once to warm the npm cache, then start Codex.

Authorization opens a browser you don’t have. Switch to the Authenticated URL as shown above.

Tool calls fail with an upstream error. That is your MCP server, not the bridge. The Logs page in MCP Nest shows its output; a missing or expired API key is the usual cause.

It worked yesterday and now returns 401. OAuth sessions expire. Re-authorize, or move to the Authenticated URL if the machine needs to run unattended.

Related guides