Migrating Model Context Protocol (MCP) servers from Claude Desktop to OpenAI's Codex does not require rewriting server logic, according to a new guide published on DEV.to. The transition is purely a configuration format shift, moving from JSON structures in Claude to TOML files in Codex. The author, who operates the PickAPlugin directory, confirms that the servers themselves remain unchanged, with only the wrapper configuration requiring adjustment.

Configuration Format Differences

Claude Desktop and Cursor store MCP server definitions in JSON files, whereas Codex utilizes TOML configuration located at ~/.codex/config.toml or within project-specific .codex/config.toml files. A typical server entry in Claude's JSON format defines a command and arguments under an mcpServers key. In Codex's TOML format, this becomes a distinct table header [mcp_servers.name], with command and args as direct keys. The CLI and IDE extensions both read from this same TOML file, ensuring consistency across development environments.

Migration Pitfalls and Best Practices

Developers must handle environment variables carefully during migration. In JSON, environment variables are nested objects, but in TOML, they must be converted to inline tables. For remote servers, the url key replaces command, and any necessary headers should be placed in http_headers. To maintain security, the guide recommends using bearer_token_env_var to reference environment variables rather than hardcoding tokens directly into the config file. Local stdio servers require no changes, as they execute the same commands regardless of the host application.

CLI Shortcuts and Automation

For users preferring command-line operations over manual file editing, Codex offers direct server management commands. Running codex mcp add followed by the server name and execution command registers the server without touching the config file manually. The codex mcp list command verifies registered servers. For those managing multiple servers, the author created a browser-based converter at pickaplugin.com that transforms JSON to TOML and vice versa, ensuring no data leaves the local machine during conversion.

Key Takeaways

  • MCP servers are platform-agnostic; only configuration syntax changes between Claude (JSON) and Codex (TOML).
  • Codex configuration files reside in ~/.codex/config.toml or project-local .codex/config.toml directories.
  • Environment variables must be converted from nested JSON objects to TOML inline tables during migration.
  • Use bearer_token_env_var in TOML to avoid hardcoding sensitive tokens in configuration files.

The Bottom Line

This migration path proves that MCP is becoming a genuine standard rather than a vendor-specific lock-in. The friction lies entirely in configuration syntax, not server implementation, which bodes well for cross-platform agent development.