DEV Community: Jameson

VS Code ignored my MCP config for an hour and never said a word

Jameson — Wed, 16 Sep 2026 12:14:15 +0000

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.

Context7 fixed the thing I kept blaming myself for

Jameson — Wed, 09 Sep 2026 09:19:15 +0000

I'm a vibe coder. I describe what I want, I read the diff, and if it runs I keep going. That gets me a long way, and then it fell apart in a very specific and very confusing way.

The setting

I was building a small static site with Astro. I needed to load a folder of Markdown files and list them. Bread and butter stuff. I asked for it, and got back something like this:

const posts = await Astro.glob('./posts/*.md');

Confident, idiomatic, and completely non-existent.

Astro.glob() was removed in Astro 6. I'm on Astro 7. There was no deprecation warning first, it was simply gone, and the error I got was the kind of unhelpful undefined-is-not-a-function noise that makes you assume you've misconfigured your own project.

So I did what a vibe coder does: I assumed it was me. I checked my folder structure. I moved files around. I asked the assistant to fix its own error, and it produced a content-collections config in the old shape (src/content/config.ts, no loader) which was also removed in Astro 6. Two wrong answers in a row, both of which used to be exactly right.

I lost most of an evening to this before the penny dropped. The assistant wasn't hallucinating. It was answering correctly for Astro 4, and nobody had told it Astro 4 was over.

Why prompting harder doesn't help

This took me too long to understand. A model's library knowledge is frozen at its training cutoff, and it has no way to know which version of Astro is in my package.json. So it averages everything it ever saw, and for a library that's shipped three majors since, the average is wrong.

You can't prompt your way out of missing information. Telling it to "use the latest Astro API" just makes it confidently guess what latest means.

What Context7 actually does

Context7 is an MCP server whose entire job is to fetch current library documentation and put it into the model's context before it answers. The model is unchanged and the output isn't post-processed. It's a retrieval step in front of the thing that was already guessing. It exposes two tools: one that maps a name like "Astro" to a library it has indexed, and one that fetches the current docs for it, optionally scoped to a topic so you're not dumping an entire manual into your context window.

The install I'd recommend is the remote HTTP one, because there is genuinely nothing to install:

claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp

There's no npx, no Node process idling in the background, and no package to keep current. Most guides lead with a local installer; skip it unless you specifically want a local process. Restart, then run claude mcp list and check context7 is in it. Other editors take the same URL as JSON, and annoyingly no two of them agree on the shape: Cursor and VS Code want different top-level keys. I wrote each one down so I'd stop re-deriving them.

Then I asked the same question again, with use context7 on the end. This time it came back with the actual current API:

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const posts = defineCollection({
  loader: glob({ base: './src/content/posts', pattern: '**/*.md' }),
});

Which is right, and which I would not have got to on my own without reading the migration guide I was specifically trying to avoid reading.

What changed, concretely

The failure mode I described at the top has stopped happening. The specific thing where I burn an evening on an API that was removed two majors ago is gone, because the docs are in the prompt now.

Two honest caveats. It doesn't make the model better at programming: my logic bugs are still entirely mine. And it only knows public library documentation, so it has nothing to say about my own modules.

The case for it is narrow and extremely common: a library moving faster than the model's cutoff, and a version you can name. If you've ever argued with an assistant about whether a method exists, and then found out you were both describing real APIs from different years, this is what fixes it.

If you get stuck wiring it up, the error strings are their own adventure and I wrote them down at mcpcontext7.com/troubleshooting. MCP error -32000 means two completely different things depending on the message next to it, which I discovered the slow way.