Claude Desktop stores local MCP servers below mcpServers in JSON. Codex stores them below [mcp_servers.<name>] in TOML. Preserve the server name, command, argument order, environment keys, and URL exactly; only the container syntax should change.
Start from the smallest working entry
{
"mcpServers": {
"tickets": {
"command": "npx",
"args": ["-y", "@example/ticket-server"],
"env": {"TICKET_TOKEN": "${TICKET_TOKEN}"}
}
}
}
Copy one server, not the entire desktop configuration. That makes it obvious which warning belongs to this move.
Map the fields before converting
| Claude JSON | Codex TOML | Keep unchanged |
|---|---|---|
mcpServers.tickets | [mcp_servers.tickets] | Server ID |
command | command | Executable |
args | args | Order |
env | [...env] | Key names |
url | url | Endpoint |
Convert, then compare meaning
Paste the JSON into MCP Config Lab and choose Codex TOML. Before saving, compare four things: server name, executable, argument order and environment keys. Quoting may change; behavior must not.
[mcp_servers.tickets]
command = "npx"
args = ["-y", "@example/ticket-server"]
[mcp_servers.tickets.env]
TICKET_TOKEN = "${TICKET_TOKEN}"
Do not “fix” the placeholder into a token
A common migration mistake is replacing the placeholder with the real credential just to get the first launch working. The config then lands in shell history, backups or Git. Keep the reference and provide the value through the environment or the secret mechanism supported by your setup.
Scan before installation
Run the TOML through MCP Config Guard. Review unpinned packages, shell wrappers, broad filesystem paths and anything that resembles a secret. A warning is a prompt to inspect, not an automatic verdict.
If Codex cannot start the server, run the exact command and arguments in a clean terminal. This separates a process problem from a TOML problem.
Confirm the actual runtime
Restart Codex, list the server, and invoke one read-only tool. Check that the process receives the intended environment variable without printing its value.
Three failures that look like conversion bugs
Codex cannot find the executable
The desktop app and your shell may have different PATH values. Run the exact executable in the same environment that starts Codex.
The JSON used a real token
Conversion preserves values; it cannot make an exposed secret safe. Rotate it, replace it with an environment reference, and scan the TOML before committing.
The server starts but no tools appear
Run the command outside the client and inspect stderr. A startup exit, missing working directory, or protocol output written to the wrong stream can look like an empty connection.
Conversion checklist
- Convert one known-working server first.
- Compare command and arguments character for character.
- Keep credentials outside committed TOML.
- Restart Codex after changing its config.
- Invoke one read-only tool before migrating the next server.
Related MCP configuration help
After conversion, use the MCP config security scanner. If a remote server returns an authorization error, continue with the MCP OAuth 401 troubleshooting guide.
Expected result
The same package starts with the same arguments, the token stays outside the committed file, and a read-only tool call succeeds.
Convert your MCP config →