Servers under no recognised key
The file parses, the client finds nothing, and no error appears anywhere
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"]
}
}MCP Server Config Validator
Paste an MCP config and get the reasons it will not work: the wrong servers key, a relative command, npx without -y, docker without -i, and any credential written into the file. Credentials are reported by key and length, never echoed.
Paste below, or drop a file anywhere on this panel
Or drop a file anywhere on this panel. Nothing is uploaded: the analysis runs in this tab.
The answer appears here
Paste on the left and press Validate. Nothing leaves this tab.
Formatted
Results
Nothing else to flag.
No formatting problems, and nothing the rules object to. Worth remembering what that covers: this reads the file you pasted, not the account or cluster it will be applied to.
No finding matches that filter.
Examples
Real input you can load into the tool above. Each one shows a different thing going wrong, because that is what the tool is for.
docker run -it
The -t is habit from interactive shells and it corrupts the framing by echoing input back
{
"mcpServers": {
"db": {
"command": "docker",
"args": ["run", "-it", "--rm", "my/mcp-server"]
}
}
}args written as a string
One argument containing a space, not two arguments
{
"mcpServers": {
"a": { "command": "npx", "args": "-y @scope/server" }
}
}Common mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Putting the servers under the wrong key
Claude Desktop and `.mcp.json` read `mcpServers`; VS Code reads `servers`. The wrong one parses cleanly and produces an empty server list with no error anywhere, which is why it survives so long.
Instead:Match the key to the client that will read the file.
Writing `docker run -it`
`-i` is required to keep stdin open. `-t` allocates a TTY, which echoes input back and rewrites line endings, and both land in the middle of the JSON-RPC stream.
Instead:`-i` alone, plus `--rm` so a stopped container is not left behind on every client restart.
Adding a comment to explain a server entry
`claude_desktop_config.json` and `.mcp.json` are strict JSON with no comments and no trailing commas. One of either makes the whole file unparseable, which takes out every server rather than the one you edited.
Instead:Keep notes outside the file. Only VS Code's `mcp.json` is JSONC.
What a client tells you when a server fails, and what it does not
"Server disconnected" covers a crash on import, a missing binary, a prompt nobody answered and a config the client never read. This separates the ones visible in the file from the ones that are not.
The wrong key means an empty list, not an error
Claude Desktop and .mcp.json read mcpServers. VS Code reads servers. A file that parses as JSON but puts the entries anywhere else produces no servers and no complaint, because from the client's point of view you configured nothing. This is the failure that survives longest, since the file looks obviously correct.
docker needs -i and must not have -t
stdio needs stdin held open, which is what -i does. A TTY, which is what -t does, echoes input back and rewrites line endings; both land in the message stream and corrupt the framing. -it is muscle memory from interactive shells and is exactly wrong here. Use -i alone, and add --rm unless you want a stopped container for every client restart.
args is an array, and "-y pkg" is one argument
Writing args as a string passes a single token containing a space, which the command sees as one strange argument rather than two. The error that comes back is from the package manager and does not mention the config.
${input:…} only resolves in VS Code
It is a VS Code feature backed by its secret storage. Anywhere else the literal placeholder text is handed to the server as the value, so the server reports an authentication failure and the mistake reads as a bad credential rather than a config one.
What this cannot see
Everything outside the file. Whether the command exists on your machine, whether the package resolves, whether the URL is reachable, whether the server crashes two lines into its own startup, and whether your client version supports the fields used here. It runs entirely in your browser and makes no request anywhere, so nothing about your actual environment is available to it. A config that passes here and still fails is a runtime problem: capture the session and use the stdio session debugger, or check the client's server log for stderr.
More mcp tools
MCP Server Config Generator The config, and why yours does not start MCP Tool Schema Validator The keywords the client ignores MCP Tool Definition Linter What your tool list costs every request MCP JSON-RPC Message Validator Request, response or notification MCP stdio Session Debugger The print statement that broke the stream MCP Capability Negotiation Checker What the two sides actually agreed MCP Resource URI Validator Expand the template, see the result
Comments and trailing commas are not JSON
VS Code's mcp.json is JSONC and accepts both. claude_desktop_config.json and .mcp.json are strict JSON and accept neither. A single trailing comma makes the whole file unparseable, which takes out every server in it rather than the one you just edited, so the symptom is that everything stopped working at once.