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

[vishk23]

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.

[vishk23]

Update: the upstream fix is merged — add-mcp shipped it in neon-solutions/add-mcp#86 as part of v2.0.0 (re-installs now replace a same-named server entry atomically instead of deep-merging, which eliminates the stdio/remote hybrid that bricks Codex).

Not yet published to npm as of today (latest is still 1.14.0), so setup mcp remains affected until the 2.0.0 release lands. Once it does, the unpinned npx -y add-mcp shell-out picks it up automatically — though pinning add-mcp@^2 at that point would guarantee it. The new replace semantics are exactly what setup mcp wants, since it always passes the complete server config.