VS Code's mcp.json: The Full Schema, With Real Examples

VS Code reads MCP servers from a .vscode/mcp.json file in your project, or from an equivalent user-level file opened via "MCP: Open User Configuration" — both use a top-level servers key, not mcpServers like Claude Code and Cursor use for the same purpose. Each entry is either a local server (command plus an args array, run over stdio) or a remote one (a single url, for a Streamable HTTP or SSE endpoint), and any secret goes in a separate inputs array instead of being typed directly into the file.

The file, and the two places it can live

Workspace-level config lives at .vscode/mcp.json, in the project root, next to settings.json and launch.json. Because it's a plain file in the repo, it's meant to be committed — that's the point of putting servers here instead of in your personal settings: a team shares the same tool list.

User-level config lives outside the repo, in your VS Code profile, and you reach it through the Command Palette's "MCP: Open User Configuration" rather than by hunting for a path yourself, since the exact location depends on your OS and profile setup. Use workspace config for servers everyone on the project needs — a company database, a shared issue tracker; use user config for anything personal, like your own GitHub token or a server you use across every project.

The schema, field by field

The whole file is one object with a single top-level key, servers, whose value is a map from a name you choose to a server definition. A local (stdio) definition takes command (the executable — often npx, uvx, or a direct binary path), args (an array of strings passed to it), and an optional env object for environment variables the process needs at launch. A remote definition drops command and args entirely and takes url instead — the address of a hosted MCP endpoint that speaks Streamable HTTP or SSE; GitHub's own Copilot MCP server, for example, is exposed this way at https://api.githubcopilot.com/mcp rather than shipped as an installable package.

Alongside servers, the file supports a top-level inputs array for anything you don't want hardcoded: each entry has a type (promptString for free text, with an optional password: true to mask it as you type; pickString for a fixed menu of choices; or command to shell out to a credential helper), an id, and a description. Inside a server's env block you reference the resolved value as ${input:that-id} — VS Code prompts for it the first time the server starts and remembers it after that, so the token itself never appears in the checked-in file.

Two worked examples

A local server, wired to run a documentation-fetching package over stdio: { "servers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } }.

A remote server, pointing at a hosted endpoint with no local process at all — just a name and a url. This is the shape for any MCP server whose operator runs it themselves and exposes it over HTTP, which is increasingly how project-management and SaaS tools ship their MCP integration rather than as an npm package you run yourself.

A prompted secret, combined with the inputs array above, looks like this inside a server's env block: "env": { "API_TOKEN": "${input:my_token}" }, alongside a matching entry — { "id": "my_token", "type": "promptString", "password": true } — in the top-level inputs array.

How this differs from Claude Code and Cursor

Open a Claude Code or Cursor config side by side with a VS Code one and the inner object — command, args, env, or url — is byte-for-byte the same convention. The only structural difference is the outer key: servers in VS Code, mcpServers everywhere else. Porting a config from one to the other is a single find-and-replace on that one key, not a rewrite.

It's also the single most common reason a pasted config silently does nothing in VS Code: someone copies a mcpServers block from a Claude Code README and drops it in as-is, and VS Code, seeing a key it doesn't recognize, just ignores the file rather than erroring.

Where to get real values instead of typing them from memory

MCPizy's directory catalogues 344 MCP servers, and most fiches show the command and args (or url, for a remote server) that server needs — a minority carry no usable command, in which case the server's own README is the source — the same values that go straight into the servers block described above, once you've renamed the outer key.

/for/vscode adds a curated top-10 list specifically for VS Code and Copilot users, with a full worked config example, if you'd rather start from a shortlist than browse all 344 individually.

Frequently asked questions

Is the mcp.json schema the same across every VS Code version?

The servers key and the command/args/url shape have been stable since MCP support in VS Code reached general availability in version 1.102 (July 2025). If you're on an older build, update first — nothing here will work on a pre-GA install.

Can I commit .vscode/mcp.json to git?

Yes, and that's the intended use for workspace-level config — it's how a team shares the same server list. Just make sure every secret is routed through the inputs array rather than typed into command, args, or env directly, since those values do get committed along with the file.

What's the actual difference between servers and mcpServers?

Purely the key name. VS Code's schema nests server definitions under servers; Claude Code and Cursor nest the identical definitions under mcpServers. There's no functional difference in what a server definition can contain — only which outer key wraps it.

Does VS Code's mcp.json support remote servers, or only local ones?

Both. A local entry has command and args and runs over stdio; a remote entry replaces those with a single url and connects over Streamable HTTP or SSE to a server the operator hosts — no local install needed for that entry.

Where do I find the exact command or url for a specific MCP server?

Its fiche on the MCPizy directory (mcpizy.com/directory/<slug>) shows the value as published by that server's maintainer — copy it into the servers block under whichever name you want to call it locally.