I spent an hour last week convinced my MCP server was down. It wasn't. VS Code had read my config file, found nothing it recognised, and said nothing at all.
The whole bug is one word.
The two shapes
Cursor, Windsurf and Claude Desktop put servers under a top-level mcpServers key:
{
"mcpServers": {
"context7": {
"url": "https://mcp.context7.com/mcp"
}
}
}
VS Code reads servers:
{
"servers": {
"context7": {
"type": "http",
"url": "https://mcp.context7.com/mcp"
}
}
}
That is the entire bug. Nearly every MCP snippet you'll find in a blog post, a README or a vendor quickstart is written for Cursor, because Cursor got there first and its format spread. Drop one into .vscode/mcp.json and VS Code parses the file happily, because it is valid JSON, finds no servers key, and concludes you have no MCP servers configured.
Which looks exactly like never having edited the file.
Why this one is worse than a normal typo
A misspelled URL gives you a connection error. A bad command gives you ENOENT. Both of those send you somewhere useful.
This gives you nothing. No warning on startup, no entry in the MCP server list, no red squiggle in the editor. The failure and the success case are visually identical right up until you notice the server isn't in the list, and if you're new to MCP you don't yet know what the list is supposed to look like, so you assume the server is broken and start debugging the server.
I checked the endpoint with curl. I re-ran the install. I read the server's changelog looking for a breaking change. The endpoint had been fine the entire time.
What type is doing there
A detail worth getting right, because I've seen it stated too strongly.
VS Code's docs show HTTP servers written both ways. The MCP configuration reference includes "type": "http" explicitly, while the 1.100 release notes introduce Streamable HTTP with just a url and no type at all. Recent builds infer the transport from the presence of a url.
So the key name is what silently breaks your config, and type isn't. I still write "type": "http" because it's explicit and it matches the current reference, but if you're hunting a silent failure, check the top-level key first and don't get distracted by this one.
How to tell in ten seconds
Open the MCP server list from the Command Palette.
If your server is listed but failing, you have a real connectivity or auth problem, and the error string is worth reading properly. MCP error codes are their own genre of unhelpful, and I've written up what -32000 and -32001 actually mean at mcpcontext7.com/troubleshooting, because each of them covers two unrelated conditions.
If your server is missing entirely, it's the key name. Every time, in my experience. VS Code isn't failing to connect; it doesn't know there's anything to connect to.
For a working server, expanding it should show its tools. Tools appearing means the handshake completed, which is a stronger signal than the server merely being listed.
The general version of this
MCP is young enough that the clients haven't converged, and the config formats diverged early. The top-level key is the most visible difference, though Claude Desktop goes further and can't take a remote URL from its config file at all, which surprises people who assume every client accepts the same JSON with a different wrapper.
The practical rule I've settled on: never adapt a config from one client to another. Copy it from something written for the client you're actually using. Adapting looks easy and is where the silent failures live.
I got tired of re-deriving these, so I wrote down the exact JSON for each client. VS Code, Cursor, Claude Desktop and Windsurf all have their own page, because no two of them agree.
If you're staring at a config that looks right and a server that isn't there, check the key. It took me an hour and I'd rather it took you ten seconds.
