MCP Config Doctor
Diagnose and fix MCP client configuration problems. Supports Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, and Zed.
- ✓ Zero install — runs entirely in your browser
- ✓ Client-aware diagnosis for 7 MCP clients
- ✓ Config & logs never leave your device
1. Pick a tab → 2. Paste or fill the config → 3. Review findings or copy the config
How to use it
Diagnose
Paste a config or log
Select your client and OS, paste your JSON/JSONC, and optionally add an error log. You get grouped findings, deterministic fixes you can apply, and verification steps.
Generate
Describe the server
Pick a client, transport, command or URL, and optional env vars or headers. The generator emits the exact JSON shape that client expects.
Verify in the client
Restart and test
Copy or download the config, place it in the path shown for your client, and restart. Static checks cannot prove the server is running; confirm in the client log.
Top 5 MCP configuration errors
These five configuration mistakes show up repeatedly in "my MCP server won’t start" reports. The doctor above flags each pattern statically, before you restart the client.
1. Trailing commas
JSON does not allow a comma after the last item in an object or array. A trailing comma is a common reason an MCP client fails to parse a config file.
2. Unescaped Windows backslashes
A path like C:\tools\npx.cmd can fail in two ways. Single backslashes such as \t or \n form valid JSON escapes but change the path (C:\tools\npx.cmd becomes a tab and a newline). Other sequences, such as \p or \m in C:\path\mcp, are invalid JSON escapes and stop parsing entirely. Use forward slashes (C:/tools/npx.cmd) or escape each backslash as \\.
3. python vs python3
On macOS and many Linux distros the python command does not exist - only python3. On Windows, python can resolve to a Store stub. The wrong interpreter name means the server never starts.
4. Mixing up transports
A stdio (command-based) server should not carry a transport field. For remote servers, the config can declare HTTP or SSE, but static diagnosis cannot tell which protocol the remote endpoint actually supports - you must confirm that in the server documentation or client log.
5. URL without http(s)://
Remote servers must use a full http:// or https:// URL. A bare host like example.com/mcp fails validation in MCP clients that require an HTTP(S) scheme.
Client configuration guides
Each guide covers that client’s config file location, a working example, and the pitfalls that only happen on that client.
Add an MCP server to Claude Desktop
claude_desktop_config.json paths, local stdio only, and remote servers via Connectors.
Add an MCP server to Cursor
Project vs global mcp.json, one-click installs, and "Client closed" errors.
Add an MCP server to VS Code
.vscode/mcp.json with top-level "servers", user settings, and the inputs feature for secrets.
Add an MCP server to Windsurf
mcp_config.json location and reloading Cascade after edits.
Add an MCP server to Zed
The "context_servers" object inside settings.json and JSONC comment support.
Add an MCP server to Cline
MCP settings opened through the Cline panel, streamableHttp for HTTP, and autoApprove.
Problem guides & reference
Evidence-first troubleshooting for specific failure intents, plus a compatibility matrix derived from the same adapter data as the tool above.
MCP client compatibility matrix
Wrapper keys, transports, remote URL fields, and config locations for all seven clients - derived from the same data as the tool.
VS Code MCP server not showing
The "servers" vs "mcpServers" wrapper mistake, unstarted servers, and agent-mode visibility.
Claude Desktop MCP not showing on Windows
%APPDATA% config location, backslash escapes, stdio-only JSON, and the full-restart rule.
spawn ENOENT / npx not found
What the error actually points at, GUI-vs-shell PATH gaps, and the Windows npx.cmd boundary.
stdio vs SSE vs Streamable HTTP
An MCP transport is the channel a client uses to talk to a server. Picking the wrong one is a top-5 configuration error.
| Transport | Config uses | Best for | Status |
|---|---|---|---|
| stdio | command + args | Local servers the client launches itself | Current standard |
| Streamable HTTP | url + "type": "http" | Hosted / remote servers | Current standard |
| SSE | url + "type": "sse" | Older remote servers | Deprecated by the MCP spec |
Static diagnosis can check that the config uses the right fields for the selected client, but it cannot determine whether a remote endpoint actually speaks Streamable HTTP or SSE. Always confirm the transport against the server documentation or the client log.
Frequently asked questions
What is MCP Config Doctor?
MCP Config Doctor is a free, in-browser tool that diagnoses and fixes Model Context Protocol client configuration problems. It checks your JSON against client-specific rules derived from official documentation, spots cross-client wrapper mistakes, and matches pasted error logs against known runtime patterns — all without uploading your config anywhere.
Which clients are supported?
Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, and Zed are fully supported. Each client gets the exact JSON shape, wrapper key, and remote-server fields it expects.
Is my config uploaded to a server?
No. Diagnosis, generation, and fix proposals are all performed by JavaScript running in your browser. No network request ever carries your config, so API tokens inside env variables or headers stay private.
Why does my config still fail after "static checks passed"?
Static checks can prove that a config is valid JSON and follows the client-specific rules, but they cannot prove the server binary is installed, the PATH is right, credentials are valid, or a remote URL is reachable. "Static checks passed" only means no blocking configuration problem was found; always verify runtime behavior in the client itself.
Where do I put the generated config file?
It depends on the client and scope. VS Code uses a top-level "servers" object (project scope: .vscode/mcp.json). Zed uses "context_servers" inside settings.json. Cline opens its MCP settings through the Cline panel -> MCP Servers -> Configure. Claude Desktop uses claude_desktop_config.json for local stdio servers only; remote servers are added via Settings > Connectors. Claude Code supports project (.mcp.json), user (~/.claude.json), and local scope (via the CLI). Windsurf uses ~/.codeium/windsurf/mcp_config.json. The generator shows the exact location for the client you select.
What file types can I diagnose?
You can paste JSON/JSONC text or choose a local .json, .jsonc, or .txt file. Files are read with the browser File API and are never uploaded.
Does this tool start or connect to my MCP server?
No. It only inspects the config text and any error log you paste. It never spawns processes, makes network requests, or talks to a real MCP server.
What is an MCP config?
An MCP config is a JSON file that tells an AI client which Model Context Protocol servers to start and how to reach them. Each server entry defines either a local command to launch (stdio transport) or a remote URL to connect to (HTTP or SSE transport).