`setup mcp` can brick Codex (invalid config: url is not supported for stdio) via add-mcp merge bug

Start at the setup mcp implementation that shells out to npx -y add-mcp, then review neon-solutions/add-mcp#83 and the generated ~/.codex/config.toml entry. Determine whether this repository should pin a fixed add-mcp version or remove the stale stdio entry before installation. Done means rerunning the reported reproduction no longer leaves Codex with an invalid hybrid configuration.

Summary

firecrawl setup mcp can leave Codex completely unusable ("Error creating chat") when the machine has a leftover stdio-style firecrawl entry in ~/.codex/config.toml from the older firecrawl-mcp setup.

The root cause is not in this repo — setup mcp shells out to npx -y add-mcp, and add-mcp deep-merges the new server entry into an existing one with the same name instead of replacing it. The old stdio keys survive alongside the new remote ones:

[mcp_servers.firecrawl]
command = "npx"
args = [ "-y", "firecrawl-mcp" ]
type = "http"
url = "https://mcp.firecrawl.dev/<key>/v2/mcp"

  [mcp_servers.firecrawl.env]
  FIRECRAWL_API_KEY = "<key>"

Codex rejects the whole config file on this hybrid entry:

Error creating chat
invalid configuration: url is not supported for stdio
in `mcp_servers.firecrawl`

and every chat fails until the user hand-edits config.toml. Since your user base is exactly the population likely to have the old firecrawl-mcp stdio entry lying around, setup mcp is a common trigger for this even though the defect is upstream.

Repro

1. Have ~/.codex/config.toml (or CODEX_HOME) containing the classic stdio entry:

   [mcp_servers.firecrawl]
   command = "npx"
   args = [ "-y", "firecrawl-mcp" ]
   
     [mcp_servers.firecrawl.env]
     FIRECRAWL_API_KEY = "fc-test"
   

2. Run firecrawl setup mcp (or the equivalent npx -y add-mcp "https://mcp.firecrawl.dev/fc-test/v2/mcp" --name firecrawl --transport http -g -a codex -y).
3. Codex now fails to create any chat with the error above.

Observed with firecrawl-cli 1.19.6/1.19.27 and add-mcp 1.14.0 on macOS.

Status upstream

Fix submitted as neon-solutions/add-mcp#83 (replace server entries atomically on re-install instead of deep-merging). Since setup mcp invokes add-mcp unpinned via npx -y add-mcp, users get the fix automatically once it's merged and released — no change needed here in that case.

Possible mitigations in this repo

• Pin a minimum add-mcp version in the setup mcp shell-out once the fix ships (npx -y add-mcp@^1.x.y).
• Optionally have setup mcp detect/remove a stale stdio firecrawl entry before installing the remote one, which would also protect users of other agents' config files.