The cases follow the converter's JSON parser, server normalization, diagnostics, and Codex TOML serializer. They test preservation, intentional field renaming, and errors the UI should surface.
Case 1: stdio command, arguments, and environment
{"mcpServers":{"docs":{"command":"npx","args":["-y","@example/docs"],"env":{"DOCS_MODE":"read-only"}}}}
The Codex output must retain the executable, argument order, and environment key. The environment object becomes its own TOML table.
[mcp_servers.docs] command = "npx" args = ["-y", "@example/docs"] [mcp_servers.docs.env] DOCS_MODE = "read-only"
Case 2: remote server with a bearer-token reference
{"mcpServers":{"tickets":{"url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer ${TICKET_TOKEN}"}}}}
The serializer recognizes an environment-backed Bearer header and emits Codex's dedicated bearer_token_env_var field. It does not copy a token value into TOML.
[mcp_servers.tickets] url = "https://api.example.com/mcp" bearer_token_env_var = "TICKET_TOKEN"
Case 3: an environment-backed custom header
{"mcpServers":{"search":{"url":"https://search.example.com/mcp","headers":{"X-Workspace":"${WORKSPACE_ID}"}}}}
A custom header whose entire value is an environment placeholder belongs in env_http_headers. The TOML value is the environment-variable name, not the placeholder syntax.
[mcp_servers.search] url = "https://search.example.com/mcp" [mcp_servers.search.env_http_headers] X-Workspace = "WORKSPACE_ID"
Case 4: a server name that needs quoting
{"mcpServers":{"support tickets":{"command":"node","args":["server.js"]}}}
Spaces are not valid in a bare TOML key. The converter should quote the table name rather than silently replacing characters and changing the server ID.
[mcp_servers."support tickets"] command = "node" args = ["server.js"]
Case 5: conflicting transports
{"mcpServers":{"broken":{"command":"node","url":"https://api.example.com/mcp"}}}
This is not a choice the converter should make for the user. The diagnostic path reports an error because each server must define exactly one local command or remote URL. Correct the source before using any generated result.
Case 6: the wrong wrapper
{"servers":{"docs":{"command":"npx"}}}
When the selected source format is Claude Desktop, the parser expects mcpServers. A VS Code-style servers wrapper should stop conversion instead of being guessed. Selecting the correct source format is part of the input contract.
What these cases do not prove
They do not prove that a package exists, a command is safe, a remote endpoint is reachable, or the target client supports every optional field. After conversion, scan the config, restart the target client, and call one read-only tool.
Try the same fixtures
Paste each input into the converter, inspect the diagnostic state, and compare the generated TOML with the expected field mapping above.
Open MCP Config Lab →