MCP Config Validator
Paste an MCP config from Claude Desktop, Claude Code, Cursor, VS Code or Gemini CLI and see what will stop your servers from loading, which values look like leaked keys, and the same config for another client.
Last checked
Config file
Add a server
Checks
Paste your config, try the sample or add a server. Errors, leaked-looking keys and the server list appear here.
How to use it
- Open the config: in Claude Desktop use Settings, Developer, Edit Config; Claude Code reads .mcp.json in the project root, Cursor .cursor/mcp.json and VS Code .vscode/mcp.json.
- Pick the client and paste the whole file into the box. Errors, warnings and the list of servers update as you type.
- Fix each error, move any flagged secret into an environment variable, then copy the formatted JSON back and fully restart the client.
- If the JSON does not parse, press Auto-fix and check the list of changes it made.
- To move servers to another editor, open Convert to another client, pick the target, read the notes and copy or download the new file.
What it checks and why
Claude Desktop and Claude Code read MCP servers from a JSON file with one top-level mcpServers object, keyed by a server name you choose. A local server has a command and an optional args array and env object; Claude Code also accepts remote servers with a type such as http and a url, plus optional headers. One stray comma or a wrong key and the server does not appear, so this checks the shape before you restart.
The checks follow the official docs. The MCP guide for Claude Desktop shows the file location on macOS and Windows, the command and args form, and says paths in the config should be absolute. The Claude Code MCP docs define .mcp.json, the stdio, http, sse and ws types, that a url without a type is a configuration error, and where ${VAR} and ${VAR:-default} expansion works.
The four clients agree on the idea but not on the details. Claude Desktop, Claude Code and Cursor use mcpServers; VS Code uses servers, needs a type on every server and keeps prompts for secrets in a separate inputs array. Claude Code writes environment variables as ${VAR} or ${VAR:-default}, Cursor as ${env:VAR}, and VS Code points at an input with ${input:id}. The Claude Desktop guide only shows local servers in the file; remote servers are added under Settings, Connectors.
Gemini CLI keeps mcpServers in settings.json but marks a streamable HTTP server with httpUrl and keeps url for SSE, and adds cwd, timeout, trust, includeTools and excludeTools. Codex CLI uses TOML in ~/.codex/config.toml, one [mcp_servers.<name>] table per server, and reads secrets from the environment by name: env_vars forwards variables, bearer_token_env_var sets the Authorization header, and env_http_headers maps headers to variables. The converter writes ${VAR} references into those fields.
Conversion follows those docs. References are rewritten to the target's syntax, and when the target is VS Code each one becomes a promptString input (marked as a password when the name looks like a key or token, and keeping the default if there was one). Cursor documents no default syntax, so defaults are dropped with a note. Fields one client has and another does not, such as cwd, envFile, oauth, headersHelper or the ws transport, are dropped with a note instead of guessed.
Secret checks are heuristics and run only on this page; nothing is sent anywhere. A value is flagged when it starts with a prefix that providers use for their keys (Anthropic, OpenAI, GitHub, GitLab, Slack, AWS, Google, Stripe, Hugging Face, npm, or a JWT) or when it is a long string with a high Shannon entropy. References such as ${API_KEY} are never flagged.
Specs and sources
- MCP: Connect to local MCP servers (Claude Desktop)
- Claude Code: Connect Claude Code to tools via MCP
- MCP: Connect to remote MCP servers (Claude connectors)
- Cursor: Model Context Protocol (mcp.json)
- VS Code: MCP configuration reference
- Gemini CLI: MCP servers (settings.json)
- Codex: MCP servers in config.toml
- RFC 8259: The JSON data format
Limits
- It checks the file, not the servers: it cannot tell whether npx, a package or a URL actually works on your machine. The MCP logs show that.
- Unknown keys are warnings, because clients add options over time. Check the docs for a key the validator does not know.
- Relative path warnings only catch arguments that start with ./ or ../.
- Codex conversion is one way: the tool writes config.toml but does not read TOML. Windsurf and Cline files are not checked against their own key lists.
- Auto-fix repairs syntax and shape only. It does not move secrets out of the file or guess a missing command.
- Secret detection is a guess: it can miss a key with an unknown format and can flag a long random ID that is not secret. A clean result does not prove a file is safe to share.
- Conversion copies only the fields each client documents. Settings outside the file, such as Claude Desktop connectors or VS Code sandbox rules, have to be set up again by hand.
Questions
- Why does Claude Desktop say Bad escaped character?
- A Windows path in the JSON has single backslashes, such as C:\Users\me. In JSON a backslash starts an escape, so write C:\\Users\\me or C:/Users/me. Auto-fix does this for every path in the file.
- How do I add an MCP server to Codex or Gemini CLI?
- Paste a Claude or Cursor config, open Convert to another client and pick Codex CLI or Gemini CLI. Codex reads [mcp_servers.<name>] tables from ~/.codex/config.toml; Gemini CLI reads mcpServers from ~/.gemini/settings.json or .gemini/settings.json in the project.
- Where is claude_desktop_config.json?
- On macOS at ~/Library/Application Support/Claude/claude_desktop_config.json and on Windows at %APPDATA%\Claude\claude_desktop_config.json. Claude Desktop opens it from Settings, Developer, Edit Config.
- Why is my MCP server not showing up in Claude Desktop?
- The usual causes are invalid JSON, a wrong key name, relative paths or not fully quitting and restarting the app. The MCP docs also point to mcp.log and the mcp-server-NAME.log files in the Claude logs folder.
- What is the difference between claude_desktop_config.json and .mcp.json?
- Both use mcpServers. The first configures Claude Desktop. .mcp.json sits in a project root, is shared through version control and is read by Claude Code, which asks for approval before using its servers.
- How do I pass an API key to an MCP server?
- For a local server, put it in env as a string. In .mcp.json you can write ${API_KEY} so the value comes from your environment instead of the file; ${API_KEY:-fallback} adds a default.
- How do I add a remote MCP server by URL?
- In .mcp.json give the entry "type": "http" and a "url", with optional headers. Without the type Claude Code reports a configuration error.
- How do I convert an MCP config from Claude to Cursor or VS Code?
- Paste the Claude config, open Convert to another client and pick Cursor or VS Code. Cursor keeps mcpServers and switches ${VAR} to ${env:VAR}; VS Code moves the servers under servers, adds a type to each one and turns references into inputs that VS Code asks for on first start.
- Should I put API keys directly in mcp.json?
- Better not, especially in a project file that is committed. Reference an environment variable instead (${VAR} in Claude Code, ${env:VAR} in Cursor) or a VS Code input, and rotate any key that has already been committed or shared.
- Is my config uploaded?
- No. The checks run in your browser, so tokens in env or headers never leave your device.