ChatGPT (Codex) MCP server not working? Fixes that actually work

Codex (the CLI, IDE extension and ChatGPT desktop app) keeps MCP servers in a TOML file, not JSON, and gives slow servers only 10 seconds to start by default. Those two cause most of the trouble.

Last checked 2026-10-14 against the official docs and our own test runs. See which MCP servers passed in ChatGPT (Codex).

1. Edit the right config file

Servers live in ~/.codex/config.toml, or in a project-scoped .codex/config.toml. You can also add one from the terminal: codex mcp add NAME --env VAR=VALUE -- COMMAND ARGS.

2. Check the TOML

Each server is a [mcp_servers.NAME] table. This is the exact form we test with:

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]

Strings need double quotes, args is a list, and env is a table ([mcp_servers.NAME.env] with KEY = "value" lines). Check the file with:

python3 -c "import tomllib;tomllib.load(open('config.toml','rb'));print('ok')"

3. Raise the start-up timeout

startup_timeout_sec defaults to 10 seconds and tool_timeout_sec to 60. A first npx -y or uvx run that downloads the package can take longer than 10 seconds. Our tests run every server with startup_timeout_sec = 60.

4. Check the server is listed

In the Codex terminal UI, type /mcp to see active servers. From the shell, codex mcp --help lists the management commands. In the IDE extension, save the server and choose Restart.

5. Run the command yourself

Copy the exact command and args into a terminal and run them. A stdio server that starts correctly just waits silently for input (press Ctrl+C to stop). An error, a “command not found” or a crash here is the real problem, and the app's log will show the same thing.

cwd sets the folder the server starts in.

6. Environment variables and tokens

Set values in the server's env table, or forward existing ones with env_vars = ["LOCAL_TOKEN"]. For remote servers, bearer_token_env_var names the variable holding a bearer token. For OAuth servers, run codex mcp login NAME (or use /mcp in the TUI).

7. Tool calls waiting for approval

Codex can ask before running MCP tools. In non-interactive runs (codex exec), our harness sets default_tools_approval_mode = "approve" for the one server under test so its tools can run.

Problems we actually hit in testing

From our test runs on 2026-10-13 and 2026-10-14. These apply to every client, because the cause is in the server or the machine, not the app.

Wrong Node version. context-mode needs Node 22.5 or newer and failed to start under Node 20.19 in our protocol check. Draw.io MCP also needs Node 22+. Check with node --version. If your default Node is older, install Node 22 and point command at its absolute path (for example /path/to/node22/bin/npx). That is how we made both pass.
npx / uvx not found. Most servers we test start with npx -y … (needs Node.js) or uvx … (needs uv). Apps started from a dock or menu may not see the PATH your terminal uses. Run which npx / which uvx in a terminal and use that absolute path as command.
The server needs something else running. Jupyter MCP only works with a running Jupyter server. Draw.io MCP acts on a live draw.io editor that has to be open. We failed Jupyter until a local JupyterLab was started.
No Docker. Terraform MCP's documented quick start runs it in Docker. Where Docker isn't available we used HashiCorp's official release binary as the command instead.
“Private IP” or SSRF refusals behind a proxy or VPN. On our test machine, DNS resolved public sites to 198.18.x addresses (a proxy's fake-IP range). Fetch (reference), DuckDuckGo search and Open-WebSearch have private-address guards that then refused every URL. If fetch tools fail only on one network, this is a likely cause. Each server documents its own override flag; only relax it on a network you trust.
It's the website, not your setup. DuckDuckGo search sometimes got “No results” from DuckDuckGo's bot detection. That failed a search task in one of our Cursor runs (2026-10-13) even though the server was connected and working.
One mode of a server fails while another works. Fetch (reference)'s default (readability) mode exited with an error on our machine; its raw=true option worked.

Sources

Links checked 2026-10-14. Items marked “Our tests” come from our own harness runs, shown on each server page with the date.

Other guides: Claude Code · Cursor · Claude Desktop · All help