I moved my MCP servers from Claude to Codex. Here's the cheat sheet

Description and use

Migrating MCP server configurations from Claude’s JSON to Codex’s TOML while preserving functionality and secure token handling.

Problem

Migrating MCP server configurations from Claude’s JSON format to Codex’s TOML format while preserving functionality and security.

Outcome

All MCP servers function identically after migration, with tokens securely referenced via environment variables and no need to modify server commands.

Workflow

• Identify the JSON config file location (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json).
• Export or copy the JSON content.
• Convert each server entry: create a [mcp_servers.NAME] table, map command and args directly, transform env to an inline table, use url for remote servers, add http_headers for headers, and reference bearer_token_env_var for tokens.
• Save the resulting TOML to ~/.codex/config.toml or within a trusted project’s .codex/config.toml.
• Verify by running codex mcp list or using the IDE extension.
• Optionally use the CLI shortcut: codex mcp add context7 -- npx -y @upstash/context7-mcp.
• For bulk conversion, use the browser-based MCP config converter at https://pickaplugin.com/tools/mcp-config-converter.

Evidence

Claude Desktop and Cursor keep MCP servers in JSON. Codex keeps them in TOML, in ~/.codex/config.toml (or .codex/config.toml inside a trusted project).

Source

Each server becomes its own [mcp_servers.NAME] table. The CLI and the IDE extension both read the same file.

Source

env becomes an inline table. So "env": {"API_KEY": "..."} turns into env = { API_KEY = "..." }.

Source

Remote servers use url. Put any headers in http_headers.

Source

Keep tokens out of the file. For remote servers, bearer_token_env_var points Codex at an environment variable instead of pasting the token into config.toml.

Source

Or skip the file and use the CLI codex mcp add context7 -- npx -y @upstash/context7-mcp codex mcp list

Source