Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up

[20bytes]

Hi maintainers, I found a Codex CLI configuration issue while verifying the MCP setup guide and wanted to report it in case it helps reduce installation friction.

Summary

The current Codex section in docs/mcp-cli-config.md appears to describe an outdated configuration format and a port-only setup path that Codex CLI does not actually pick up.

What I observed

The guide currently says that Codex users can:

1. add an MCP server entry to ~/.codex/config.json, or
2. set MCP_HTTP_PORT=12306

During local verification, neither path worked with the current Codex CLI.

Reproduction

1. ~/.codex/config.json is ignored

I created a temporary Codex home and wrote this exact file:

{
  "mcpServers": {
    "chrome-mcp": {
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}

Then I ran:

HOME=/tmp/codex-mcp-chrome-docs-test codex mcp list

Codex reported:

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

2. The current CLI writes config.toml, not config.json

When I used the actual Codex command:

HOME=/tmp/codex-mcp-chrome-docs-test-add \
  codex mcp add chrome-test --url http://127.0.0.1:12306/mcp

Codex created:

[mcp_servers.chrome-test]
url = "http://127.0.0.1:12306/mcp"

in:

~/.codex/config.toml

and codex mcp list then showed the server correctly.

3. MCP_HTTP_PORT alone does not register a server

I also tested:

HOME=/tmp/codex-mcp-chrome-port-only MCP_HTTP_PORT=12306 codex mcp list

and got the same result:

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

So setting the port alone does not appear to make Codex discover chrome-mcp automatically.

Why this matters

Right now the guide can lead Codex users into a setup that looks reasonable but does not result in a usable MCP server entry. That makes troubleshooting harder because the failure happens before users even get to the Chrome side of the integration.

Suggested direction

It may help to update the Codex section to reflect the current CLI behavior, for example by:

• documenting codex mcp add chrome-mcp --url http://127.0.0.1:12306/mcp, or
• documenting the current ~/.codex/config.toml format if manual editing is still intended

If there is another Codex-specific auto-discovery mechanism that I missed, feel free to correct me. I just wanted to report this because the documented config.json path and the MCP_HTTP_PORT-only flow did not work in local verification.