Announcing mcp-convert — Migrate Claude Code MCP Settings to Codex CLI with Agent Skills

Introduction

More and more developers are using Claude Code and Codex CLI side by side. Both support MCP (Model Context Protocol) servers, letting you use the same tools — Playwright, Firecrawl, GitHub MCP, and more. But their configuration formats are completely different.

Claude Code stores its settings in ~/.claude.json as JSON, while Codex CLI uses ~/.codex/config.toml in TOML format. Every time you add an MCP server, you have to manually update both config files.

To solve this problem, we added a new skill called mcp-convert to the agent-skills repository. It automatically converts Claude Code's MCP settings into the Codex CLI format.

Why Do You Need MCP Config Migration?

MCP is a protocol for connecting external tools to AI agents. Both Claude Code and Codex CLI can use MCP servers, but they manage configurations differently.

Claude Code config (JSON):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"],
      "type": "stdio"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx..."
      }
    }
  }
}

Codex CLI config (TOML):

[mcp_servers.playwright]
command = "npx"
args = ["@anthropic/mcp-playwright"]
 
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
 
[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx..."

With two or three MCP servers, manual syncing is manageable. Once you have ten or more, it becomes unsustainable. Transcription errors with API keys in env values become increasingly likely.

According to OpenAI's official documentation, Codex requires the section name to be mcp_servers (with an underscore) — mcp-servers or mcpservers will be silently ignored. These subtle differences are a recipe for human error.

How Does mcp-convert Work?

mcp-convert is built around a Python script (convert_claude_to_codex.py). It reads Claude Code's ~/.claude.json and converts each server definition in the mcpServers block into the Codex CLI format.

Conversion Process

The script works through these steps:

1. Read source: Extract the mcpServers object from ~/.claude.json
2. Parse servers: Parse each server's type (stdio / http / sse / streamable_http), command, args, env, and url
3. Convert: Transform from Claude format to Codex format (JSON to TOML mapping, env value copying)
4. Output: Display dry-run preview, register in Codex, or output TOML depending on the selected mode

Supported Server Types

Env values (API keys, etc.) are copied directly from the Claude config to the Codex config. No encryption or external secret store integration is performed, so file permission management is the user's responsibility.

How to Use It

Installation

# Install only mcp-convert from agent-skills
npx skills add anyoneanderson/agent-skills --skill mcp-convert -g -y
 
# Install all skills at once
npx skills add anyoneanderson/agent-skills -g -y

Basic Usage

After installation, just ask your agent to do the conversion.

> Convert Claude MCP to Codex
> Migrate MCP settings
> Move my MCP config to Codex CLI

When the skill activates, it walks through this interactive flow.

Step 1: Server Detection

Reads ~/.claude.json and displays all registered MCP servers.

Detected servers:
- playwright: type=stdio, env: none
- github: type=stdio, env: GITHUB_PERSONAL_ACCESS_TOKEN
- firecrawl: type=stdio, env: FIRECRAWL_API_KEY

Step 2: Select Migration Targets

If multiple servers are found, you choose which ones to migrate.

Select servers to migrate:
- Migrate all (recommended)
- Only servers with secrets
- Select manually

Step 3: Select Execution Mode

Select execution mode:
- dry-run (preview only) (recommended)
- apply (register in Codex)
- export-toml (TOML output only)

Direct Command-Line Execution

You can also run the Python script directly instead of going through the skill.

# Preview (no changes)
python3 scripts/convert_claude_to_codex.py --mode dry-run
 
# Migrate specific servers only
python3 scripts/convert_claude_to_codex.py --mode apply --server github --server playwright
 
# Overwrite existing settings
python3 scripts/convert_claude_to_codex.py --mode apply --overwrite
 
# Output TOML to stdout
python3 scripts/convert_claude_to_codex.py --mode export-toml

The agent-skills Ecosystem

With the addition of mcp-convert, the agent-skills repository now contains seven skills.

Beyond the spec-driven development skills (spec-*), this introduces a new category: cross-agent configuration migration.

FAQ

Q. Does it support migration from agents other than Claude Code?

A. Currently, it only supports conversion from Claude Code (~/.claude.json) to Codex CLI. We are considering adding support for conversions between other agents such as Cursor and Gemini CLI in the future.

Q. How are API keys in env handled?

A. Env values read from Claude's config file are copied as plain text to the Codex config. No encryption or external secret manager integration is performed. Make sure to set appropriate file permissions on ~/.codex/config.toml.

Q. Will existing Codex MCP settings be overwritten?

A. By default, servers with the same name already registered in Codex are skipped. Use the --overwrite option to overwrite them. We recommend running --mode dry-run first and then --mode apply.

Q. Can project-specific MCP settings be migrated?

A. Currently, only the top-level ~/.claude.json is supported. MCP overrides defined in project-specific .claude.json files need to be handled separately.

Summary

mcp-convert is an MCP configuration migration skill for developers using both Claude Code and Codex CLI.

• One-command migration: Automatically converts MCP server definitions from ~/.claude.json to Codex CLI format
• Three safe modes: Preview with dry-run, apply to register, export-toml to verify
• Built as Agent Skills: Install with npx skills add, works with 17+ agents

As multi-agent development becomes the norm, the overhead of manually syncing configurations between agents is a cost worth eliminating. We hope mcp-convert helps with that.

Repository: github.com/anyoneanderson/agent-skills

At ZenChAIne, we continue to research and develop tools and workflows that leverage AI agents. Feedback and Pull Requests are always welcome.

agent-skills をオープンソース公開 — AIエージェントによる仕様駆動開発の実践仕様駆動開発を AIエージェントのスキルとして実装した agent-skills をオープンソース公開しました。zench-aine.io

Agent Skills とは何か — AIエージェントに再利用可能なスキルを追加する仕組みSKILL.md フォーマットの仕組み、カスタムスラッシュコマンドとの違い、対応エージェント、自作方法を解説します。zench-aine.io

References

• Codex CLI - Model Context Protocol
• Codex CLI Configuration Reference
• agent-skills Repository