VS Code mcp.json Location: MCP Server Config and Registry, Step by Step

You add an MCP server to VS Code, reload the window, open Copilot Chat, and the new tools are nowhere to be found. Most of the time the server is fine and the file is the problem: it sits in the wrong folder, it uses the wrong top-level property, or VS Code is reading a different copy than the one you just edited. This article pins down the VS Code mcp.json location for every setup, shows the JSON shape the editor expects, and shows how the MCP registry fits in so you can add servers without copying commands from random READMEs.

The Model Context Protocol (MCP) is the open standard that lets an AI assistant call outside tools: read a folder, query a database, open a pull request. VS Code acts as the MCP client, and every server you enable shows up as a set of tools in agent mode. The whole setup lives in one small JSON file, which is exactly why a wrong path or a wrong property name fails so quietly.

Where mcp.json Lives

VS Code reads MCP server definitions from two main places, plus a portable format described further down. Think of them as a team shelf and a personal shelf.

Workspace file: .vscode/mcp.json

The workspace file sits inside the project folder at .vscode/mcp.json. Create the .vscode folder if it does not exist, drop the file in, and VS Code picks it up. Because it travels with the repository, everyone who clones the project gets the same server list.

You can also open it from the Command Palette (Ctrl+Shift+P on Windows and Linux, Cmd+Shift+P on macOS) with MCP: Open Workspace Folder Configuration, or create an entry through MCP: Add Server and choose the workspace option.

User file by operating system

The user file applies to every window you open. The fastest way to reach it is the Command Palette command MCP: Open User Configuration, which opens the copy that belongs to your active profile. On a standard install the file sits in the VS Code user data folder:

💡 Tip: VS Code Insiders keeps its own data folder, usually named Code - Insiders instead of Code. If an edit changes nothing, check that you are not editing the stable copy while running Insiders. When in doubt, trust the Command Palette command over any path you typed from memory.

Which one to pick

The choice comes down to who needs the server and whether it carries a personal token.

Avoid defining the same server name in both files. With two copies you can no longer tell which one is actually running, and a bug report that says "the server is broken" turns into an afternoon of guessing.

Writing the File Format Correctly

The file has up to three top-level sections: servers (required, a map of server names to settings), inputs (optional, prompts for values you do not want to store), and sandbox (optional, file and network rules on macOS and Linux). Everything else hangs off those three.

A minimal stdio server

A stdio server is a program VS Code starts on your machine and talks to through standard input and output. Most community servers ship this way, usually through npx or uvx.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copy Prompt

The ${workspaceFolder} variable expands to the open project, so the same file works on every teammate's machine. You can add cwd for the working directory, env for environment variables, and envFile to load variables from a file.

A remote HTTP server

A remote server runs somewhere else and VS Code connects to its URL. No local process, no npx, no Node version problems.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copy Prompt

Use "type": "http" for current remote servers and "type": "sse" for servers that still use the older server-sent events transport. Remote entries can also carry headers for authentication and an oauth object when the server supports a browser sign-in.

The servers vs mcpServers Trap

This is the single most common reason a pasted config does nothing.

Why your server never appears

Most READMEs show a snippet written for Claude Desktop, Claude Code, or Cursor. Those clients use a top-level property called mcpServers. VS Code's own mcp.json expects servers. Paste the wrong shape into .vscode/mcp.json and the file can fail quietly: the editor may flag the property, but the warning is easy to miss, and no tools show up.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Copy Prompt

That block belongs to another client. For VS Code, rename the top-level property to servers and add "type": "stdio" so the entry matches the format shown earlier.

VS Code also documents a portable format: a .mcp.json file at the project root, or ~/.copilot/mcp-config.json for the user. Those portable files do use mcpServers. The rule is simple: servers inside VS Code's mcp.json, mcpServers inside the portable files.

Property names by client

Run through this short list whenever tools go missing:

• Check the property name first. servers for mcp.json, mcpServers for portable files.
• Check the type. A local program needs stdio, a URL needs http or sse.
• Check the file you opened. Run MCP: List Servers and confirm your server appears there.
• Reload the window after a large edit if the server list looks stale.

Keep Secrets Out of the File

A workspace mcp.json usually lands in Git. Anything you type into it, a token included, lands there too.

Prompt for tokens with inputs

The inputs section defines values VS Code asks for instead of storing them. Reference one anywhere in a server entry with ${input:id}.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "API token for the image service",
      "password": true
    }
  ],
  "servers": {
    "image-service": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

Copy Prompt

The URL above is a placeholder. The pattern is what matters: promptString with password: true shows a masked field, VS Code asks for the value when the server starts, and the token never has to sit in the file. Two other input types exist: pickString for a fixed list of options, and command for a value produced by running a command.

💡 Tip: The same pattern fits any REST service that uses a Bearer token, including the Picasso IA developer API at api.picassoia.com/v1, whose tokens start with pia_sk_. Keep that token in an input or an environment variable, never in a committed file.

envFile and workspace trust

For stdio servers, envFile loads variables from a file such as ${workspaceFolder}/.env. Add that file to .gitignore before the first commit, not after.

Trust works in two layers. Servers defined in the workspace inherit Workspace Trust, so an untrusted folder does not start them. Servers defined outside the workspace trigger their own trust prompt the first time they run. The chat.mcp.autostart setting controls restarts when a config changes, with the values never, onlyNew, and newAndOutdated (the default).

Finding Servers in the Registry

Hand-writing every entry gets old fast. VS Code gives you two ways to skip it.

Browse with @mcp in Extensions

Open the Extensions view (Ctrl+Shift+X) and type @mcp into the search box. The list that appears is the in-editor gallery of MCP servers. Pick one, choose whether to install it into your user profile or the workspace, and VS Code adds the entry to the matching mcp.json. Open the file afterward and read what was written. It is a good way to see correct syntax for servers you later add by hand.

What the official registry adds

The official MCP Registry is the public directory where server authors publish their servers. Each entry names the package or the remote URL, which is exactly what you would otherwise paste into mcp.json yourself. Use it when a server is not in the Extensions gallery, and check the package name against the registry entry before you run anything. A typo in an npx argument can install a different package.

Auto-detect servers from other apps

VS Code can also import servers you already configured in other tools. Open Settings, search for chat.mcp, and look for the setting that controls auto-detection from other applications. If you want a clean slate, switch it off. If you moved from Claude Desktop, leaving it on saves retyping.

Fix a Server That Won't Start

When a server shows an error, the answer is almost always in its own log.

Read the output log

Run MCP: List Servers, select the server, and open its output. You can also open mcp.json and look above the server name, where VS Code shows inline actions to start, stop, restart, and show output. The log prints the exact command VS Code ran and whatever the process wrote to standard error. Read the first error, not the last.

Common failure patterns

Dev mode and sandbox

If you build servers, the dev object on a stdio entry helps. watch takes a glob pattern and restarts the server when matching files change, and debug attaches a debugger (Node.js and Python are supported for stdio servers). On macOS and Linux, the sandbox object restricts what a server may touch: filesystem.allowWrite, filesystem.denyRead, filesystem.denyWrite, network.allowedDomains, and network.deniedDomains. Set sandboxEnabled on an individual server to apply it. Start tight and open up only what the server proves it needs.

Draft Your Config With Claude Sonnet 5

If a language model is going to help with JSON, make it a model built for code. Claude Sonnet 5 on Picasso IA writes and debugs code, reads screenshots, and lets you pick how hard it thinks. Here is the workflow that works for mcp.json.

1. Open the model page. Go to Claude Sonnet 5 on Picasso IA.
2. Fill the System Prompt once. Something like: You write VS Code mcp.json files. Use the servers property, never mcpServers. Always set type. Output JSON only.
3. Describe the setup in Prompt. Name the servers you want, the operating system, and whether each should be stdio or remote.
4. Set effort. Leave it on low for a one-line fix. Use medium or high when the file combines several servers and inputs. The low setting turns thinking off, so it is the fastest and cheapest.
5. Keep Max Tokens at the default of 8192. A config file needs far less.
6. Attach a screenshot if you have an error. The optional Image field accepts one, and Max Image Resolution defaults to 0.5 megapixels to keep it cheap.
7. Run it, then verify. Paste the result into mcp.json, compare every package name and URL with the registry entry, and watch the output log on first start.

A prompt that gets a usable first draft:

Create a VS Code mcp.json for Windows with two servers: a stdio filesystem
server limited to the workspace folder, and a remote HTTP server at
https://mcp.example.com/mcp that needs a Bearer token. Ask for the token
with an input so it is never stored in the file.

Copy Prompt

💡 Tip: Models can invent package names that look right and do not exist. Treat any generated args array as a draft until you have matched it against the registry.

Other chat and coding models on the platform handle the same job, so try a few and keep the one that follows your system prompt best:

Make Your Own Visuals With Picasso IA

A working MCP setup deserves documentation people actually read. A README with a clear hero image, a diagram that shows how your servers connect, or a short tutorial thumbnail makes a setup page feel finished. Picasso IA can produce all of those.

Start with Picasso IA Image for a fast first draft, try GPT Image 2 when your visual needs readable text, and use Picasso IA Image Editor Pro to adjust an image you already have. For photorealistic scenes, Seedream 4.5 is worth a test run. The platform also includes text-to-video and other generators, and you can browse every option on the all models page.

Write one prompt, generate a few variations, pick the one that fits your page, and drop it into your docs. The best way to find out what works for your project is to try it, so open Picasso IA, type a scene you want to see, and make your first image today.