AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Adding an MCP server to Codex CLI config.toml — what codex mcp add writes to the file (Windows, temp CODEX_HOME)

One line summary

Type codex mcp add <name> -- <command> <args>... and an [mcp_servers.<name>] table appears in config.toml. The Windows path we passed was stored in single quotes, and writing the same path inside double quotes with the backslashes intact made codex mcp list fail with a TOML error.

To keep the real configuration untouched, this round pointed CODEX_HOME at a temp folder.

Who this is for

• Anyone attaching an MCP server (here, @modelcontextprotocol/server-filesystem) to Codex CLI
• Anyone deciding whether to edit config.toml by hand or let the command do it
• Anyone getting TOML parse error after editing config.toml

Test environment

1. The commands available

codex mcp --help lists these subcommands: list, get, add, remove, login, logout, help. Usage for add:

Usage: codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...)
...
      --env <KEY=VALUE>
          Environment variables to set when launching the server. Only valid with stdio servers
...
      --url <URL>
          URL for a streamable HTTP MCP server

A server you start locally with a command goes after --; a remote HTTP server uses --url. This note covers the first kind only.

2. Preparing a temp CODEX_HOME

The folder CODEX_HOME points to has to exist first. Give it a path that doesn't, and it stops with exit code 1.

Error: failed to resolve CODEX_HOME

Caused by:
    CODEX_HOME points to "C:\\Users\\User\\AppData\\Local\\Temp\\longtail_A\\codex_home", but that path does not exist

Once the folder existed, it came up clean and empty.

mkdir -p /c/Users/User/AppData/Local/Temp/longtail_A/codex_home
export CODEX_HOME='C:\Users\User\AppData\Local\Temp\longtail_A\codex_home'
codex mcp list

No MCP servers configured yet. Try `codex mcp add my-tool -- my-command`.

Because we put the temp folder under %TEMP%, this warning rode along on standard error with every list, add and get. It didn't affect anything.

WARNING: proceeding, even though we could not create PATH aliases: Refusing to create helper binaries under temporary dir "C:\\Users\\User\\AppData\\Local\\Temp\\" ...

3. Adding a server, and the file it writes

codex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root'

Added global MCP server 'fs'.

A new 145-byte config.toml appeared in the empty folder.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']

Only the path containing backslashes was written in single quotes. In TOML, a single-quoted string leaves backslashes alone.

Read back with codex mcp list and codex mcp get fs, it looks like this.

Name  Command  Args                                                                                            Env  Cwd  Status   Auth
fs    npx      -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_A\fs_root  -    -    enabled  Unsupported

fs
  enabled: true
  transport: stdio
  command: npx
  args: -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_A\fs_root
  cwd: -
  env: -
  remove: codex mcp remove fs

codex mcp list --json also surfaced fields like "transport": {"type": "stdio", ...}, "auth_status": "unsupported", "startup_timeout_sec": null and "tool_timeout_sec": null.

4. Environment variables, hand-edited values, and removal

Add --env and you get a separate sub-table.

codex mcp add fs2 --env DEMO_FLAG=1 -- npx -y @modelcontextprotocol/server-filesystem 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root'

[mcp_servers.fs2]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']

[mcp_servers.fs2.env]
DEMO_FLAG = "1"

add has no option for the startup timeout, so we put startup_timeout_sec = 30 under [mcp_servers.fs] by hand. codex mcp get fs picked it up as startup_timeout_sec: 30, and list --json read it as "startup_timeout_sec": 30.0.

Then we ran codex mcp remove fs2, which printed Removed global MCP server 'fs2'. and rewrote the file like this.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']
startup_timeout_sec = 30.0

Aside from the two fs2 tables disappearing, the 30 we typed became 30.0. codex mcp add/remove looks like it rewrites the whole file, so if you keep comments or formatting in there, check on a copy before running it against the real file (we did not measure whether comments survive).

5. The common Windows mistake — backslashes inside double quotes

In a separate temp folder we wrote this by hand.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\User\AppData\Local\Temp\longtail_A\fs_root"]

codex mcp list stopped with exit code 1.

Error: failed to load bootstrap configuration

Caused by:
    0: ...\codex_home_bad\config.toml:3:63: too few unicode value digits, expected unicode hexadecimal value
    1: TOML parse error at line 3, column 63
         |
       3 | args = ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\User\AppData\Local\Temp\longtail_A\fs_root"]
         |                                                               ^
       too few unicode value digits, expected unicode hexadecimal value

Column 63 is the s right after \U in C:\Users. Exactly as the message says: inside a double-quoted string, \U was read as the start of a unicode escape, and no hex digits followed, so it stopped. Wrap it in single quotes, the way codex writes it itself (section 3). We did not check whether this error blocks other codex commands too; the one we saw it on is codex mcp list.

Results

What failed

The temp CODEX_HOME has no login information, so we never got to the step of attaching the MCP server for real and giving codex work to do. Throwing one prompt at the empty temp home with no configuration ended like this.

ERROR: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses, ...

Before that, the WebSocket connection kept failing with 401 Unauthorized up to Reconnecting... 5/5, then after a Falling back from WebSockets to HTTPS transport warning it tried over HTTPS from Reconnecting... 1/5 through 5/5 again. The final exit code was 1. We ran this from a home with empty configuration so that the MCP server would not be fetched by npx. We did not copy credentials over.

What we did not test

• We did not confirm that server-filesystem actually starts and that codex uses its tools. We never downloaded the package with npx either.
• We did not check whether codex on Windows can run npx as-is. Whether command = "npx" ever fails to start is something to look at separately in a logged-in environment.
• Beyond startup_timeout_sec, we did not look at the behavior of hand-written fields like tool_timeout_sec, cwd or enabled. We only saw their names in the list --json output.
• We did not run --url (remote HTTP servers) or codex mcp login/logout.
• We did not measure whether add/remove strips comments when config.toml has them.
• We did not try writing the path with doubled backslashes (C:\\Users\\...) or forward slashes (C:/Users/...).
• We did not check whether the PATH aliases warning goes away when CODEX_HOME is outside %TEMP%.

Related notes

• Adding an MCP server to Claude Code on Windows
• Writing codex exec results to a file
• Checking Codex CLI login status
• Installing Codex CLI on Windows