MCP.directory
All tools

Codex CLI config.toml Validator

Paste your ~/.codex/config.toml to validate [mcp_servers.X] tables and OpenAI's snake_case field schema. Runs in your browser.

Your config never leaves your browser. No upload. No login.
Paste your config.toml
Your config never leaves your browser
0 chars

Paste your config.toml above to run deterministic checks.

Or click to see how it works.

What this validator checks

  • •TOML syntax (tables, inline tables, arrays)
  • •UTF-8 BOM detection
  • •Top-level [mcp_servers.X] table shape
  • •Per-server transport (command vs url)
  • •startup_timeout_sec, tool_timeout_sec must be numbers
  • •enabled, required must be booleans
  • •enabled_tools, disabled_tools, scopes must be string arrays
  • •Env-var values must be strings
  • •Insecure HTTP for non-local URLs
  • •API key / token leak detection
  • •Duplicate / case-conflict server names
  • •Common command typos (npx, uvx, node, python)

Why this exists

OpenAI's Codex CLI is the only major MCP client using TOML — its config reference specifies [mcp_servers.X] tables and snake_case keys throughout. Configs aren't portable from Claude Desktop or Cursor without a conscious rewrite.

Common pitfalls: forgetting the underscore in mcp_servers (Claude Desktop uses camelCase mcpServers); putting JSON-styleenv: {...} instead of TOML inline-table syntax env = { K = "v" }; and quoting numbers as strings (TOML treats "30" and 30 as different types). The validator catches all three.

Frequently asked

Where is Codex CLI's config.toml?▼
Global: ~/.codex/config.toml on macOS and Linux. Project: .codex/config.toml in your repo root. The Windows path isn't published in OpenAI's official config reference (developers.openai.com/codex/config-reference); on Windows, the same ~/.codex/config.toml convention typically resolves under your user profile.
Why does Codex CLI use TOML instead of JSON?▼
OpenAI's Codex CLI was designed around TOML, a format common in Rust/Python tooling that supports inline comments and is more readable for nested config. The trade-off: configs aren't directly portable from Claude Desktop or Cursor — every key has to be re-expressed in TOML syntax (snake_case, [tables], no commas between entries).
What snake_case fields does Codex CLI accept?▼
Per the official config reference: `command`, `args`, `env`, `url`, `cwd`, `env_http_headers`, `http_headers`, `enabled`, `required`, `enabled_tools`, `disabled_tools`, `startup_timeout_sec`, `startup_timeout_ms`, `tool_timeout_sec`, `tool_timeout_ms`, `scopes`, `bearer_token_env_var`, `oauth_resource`. Note the snake_case convention — Claude Desktop uses camelCase for the few fields that overlap.
How do I migrate a Claude Desktop JSON config to Codex TOML?▼
For each server: replace the JSON object with a TOML table header. Example: `"filesystem": { "command": "npx", "args": ["-y", "x"] }` becomes `[mcp_servers.filesystem]\ncommand = "npx"\nargs = ["-y", "x"]`. Inline tables: `"env": { "K": "v" }` → `env = { K = "v" }`. Arrays: identical syntax. Drop the outer `"mcpServers":` and use `[mcp_servers.NAME]` headers per server.
What's the difference between startup_timeout_sec and tool_timeout_sec?▼
`startup_timeout_sec` is how long Codex waits for the MCP server to launch and respond to the initialization handshake. `tool_timeout_sec` is the per-tool-call timeout once the server is running. Both have `_ms` variants if you need millisecond precision. Defaults aren't documented in the reference — set them explicitly for slow-starting servers (e.g., LLM-based MCPs).
Does Codex CLI support OAuth for MCP servers?▼
Yes. Three relevant fields: `bearer_token_env_var` (name of the env var holding the token), `oauth_resource` (resource URI for OAuth resource indicators per RFC 8707), and `scopes` (array of OAuth scopes to request). Codex CLI handles the auth flow per OAuth 2.1 conventions. The validator checks structural shapes; OAuth correctness is a runtime concern.
What TOML edge cases doesn't this validator handle?▼
We use a minimal TOML parser tuned for Codex configs. It handles strings (" and '), integers, floats, booleans, arrays, inline tables, comments, and section headers ([a.b.c]). It does NOT handle: multi-line basic strings (triple-quoted), datetime values, hex/octal/binary integer literals, escape sequences inside strings (\n, \t), or dotted keys in key positions. None of these are documented in the Codex reference. If your config trips the parser, paste it into a real TOML linter.

Spotted a check we should add?

Open an issue on the directory, or browse the 2,000+ MCP servers.

← All toolsClaude Desktop validator