# How to add an MCP server to VS Code (mcp.json, .mcp.json and fixes)

> Source: <https://dev.to/pluginstackai/how-to-add-an-mcp-server-to-vs-code-mcpjson-mcpjson-and-fixes-1c9>
> Published: 2026-11-20 19:07:02+00:00

**Recommendation:** When adding an MCP server to VS Code, match the top-level key to the file (`mcpServers` for `.mcp.json`, `servers` for `.vscode/mcp.json`) and verify by invoking a tool that returns real output.
More in the playbook "Designing agent systems": <https://wpnews.pro/playbooks/agent-architecture>

Checked against the official docs: Oct 28, 2026

VS Code's agents can call tools from MCP (Model Context Protocol) servers, for example to drive a browser, read current library docs or query GitHub. The setup changed in 2026: VS Code now has two config formats in different files, and the one you pick decides which features you get. This guide shows the quickest way to add a server, which file it ends up in, and what to check when the agent can't see it. It is based on Microsoft's VS Code documentation (checked 28 October 2026).

`npx -y @playwright/mcp@latest`.` playwright`.
Microsoft's docs stress the last step: a saved config is not proof the agent can use the server. The connection works when a tool from that server is called and returns real output.

This is where most confusion comes from. VS Code reads two formats, and they use different top-level keys:

`mcpServers`: `~/.copilot/mcp-config.json` for your user (or `$COPILOT_HOME/mcp-config.json` if you set `COPILOT_HOME`), or `.mcp.json` at the root of a workspace for a team. Copilot agent sessions read these directly. This is the same `servers`: `.vscode/mcp.json` in a workspace, or the `mcp.json` in your VS Code user profile. The guided flow now labels these destinations deprecated, but they are still the only place for VS Code input prompts (`${input:...}`), `envFile`, per-server sandboxing and development mode.
Copying a block between the two formats without renaming the key is the classic mistake: a `mcpServers` block inside `.vscode/mcp.json`, or `servers` inside `.mcp.json`, is not what VS Code expects. Servers in the VS Code format are forwarded to Copilot sessions, except ones that need interactive input such as `${input:...}` variables.

The guided flow in the quick answer writes the file for you. Two extras are worth knowing:

`@playwright/mcp`. VS Code uses a model to generate the config, so review the command and arguments it proposes before allowing it. These options only appear where model-assisted setup is supported.
You can also start from Chat: **Open Customizations**, then **MCP Servers**, then **Add Server**.

`@mcp`.
The gallery is in preview, and an organization can restrict which servers are allowed. If you don't see it, use **MCP: Add Server** with the publisher's URL or command.

A local server started with a command, here the [Playwright MCP server](https://www.pluginstackai.com/plugins/playwright-mcp/) (it needs Node.js 20 or newer). Full setup: [how to set up the Playwright MCP server](https://www.pluginstackai.com/guides/playwright-mcp-server-setup/):

*.mcp.json (workspace root) or ~/.copilot/mcp-config.json*

```
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

A remote server only needs its URL. This is the [Context7](https://www.pluginstackai.com/plugins/context7/) endpoint from Microsoft's example; check the publisher's docs for sign-in and limits (for Context7, see [how to set up Context7 MCP](https://www.pluginstackai.com/guides/context7-mcp-setup/)). For the official GitHub server, including OAuth vs a personal access token, see [how to set up the GitHub MCP server](https://www.pluginstackai.com/guides/github-mcp-server-setup/):

```
{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}
```

Same Playwright server, but note the `servers` key and the explicit `"type": "stdio"`:

```
{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

For HTTP servers, VS Code tries Streamable HTTP first and falls back to SSE. Run **MCP: Open Workspace Folder MCP Configuration** or **MCP: Open User Configuration** to open these files.

*Adds the server to your VS Code user profile (VS Code format)*

```
code --add-mcp '{"name":"playwright","type":"stdio","command":"npx","args":["-y","@playwright/mcp@latest"]}'
```

The two formats handle secrets differently:

`${NAME}`, or `${NAME:-default}` for a non-secret default. Use the braced form; VS Code's client treats a bare `$NAME` as literal text. It works in `command`, `args` and `env` for stdio servers and in header values for HTTP servers. `${env:NAME}`, load a file with `inputs` entry so VS Code asks for the key the first time and stores it securely.
An input prompt, using the [Brave Search](https://www.pluginstackai.com/plugins/brave-search-mcp/) server's package and variable name:

```
{
  "inputs": [
    {
      "type": "promptString",
      "id": "brave-key",
      "description": "Brave Search API key",
      "password": true
    }
  ],
  "servers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": { "BRAVE_API_KEY": "${input:brave-key}" }
    }
  }
}
```

A server that needs a `${input:...}` value is not forwarded to Copilot sessions. If it must work there, set the key as an environment variable and use the portable format, or use OAuth if the server supports it. Never commit a file that contains a real key.

The `chat.mcp.discovery.enabled` setting lets VS Code pick up servers configured in other apps: Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json` and a workspace `.cursor/mcp.json`), Windsurf and GitHub Copilot CLI. Copilot CLI discovery is on by default; the others are off until you enable them. Setting up Claude Desktop too? See [how to add an MCP server to Claude Desktop](https://www.pluginstackai.com/guides/add-mcp-server-to-claude-desktop/).

To test, give the agent a harmless request that names the server, such as "Use the Playwright MCP server to open [https://example.com](https://example.com) and report the page title. Do not change files." Then expand the tool call in the chat and confirm it came from your server.

`mcp-config.json`).` PATH` or the runtime is missing or too old. Run the same command in a terminal to see the real error. On Windows, see `-d`. The container must stay in the foreground so VS Code can talk to it over stdio.
This guide is about connecting servers other people built. If you want to build your own MCP server, the (paid) [Agent Builder Rules + Prompts](https://www.pluginstackai.com/packs/) pack has Cursor and Claude Code rules, 2 Claude Code skills, 10 scaffolding prompts for TypeScript or Python, and 12 eval prompt templates. You don't need it just to add servers.

For a new setup, Microsoft's guided flow points you to the portable files (`~/.copilot/mcp-config.json` for yourself, `.mcp.json` for a team). Keep `.vscode/mcp.json` when you need input prompts, `envFile`, sandboxing or development mode, which only the VS Code format supports.

On macOS and Linux, yes: in the VS Code format, set `"sandboxEnabled": true` on a stdio server and add a `sandbox` object with allowed write paths and network domains. It is not available on Windows. Tool calls from a sandboxed server are auto-approved, so set the rules carefully.

The portable format uses the same `mcpServers` shape as Cursor's `mcp.json`, but the file locations differ. See [how to add an MCP server to Cursor](https://www.pluginstackai.com/guides/add-mcp-server-to-cursor/).

Commands and config above come from these official docs. Tools change often, so check them for the latest steps.

PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email [pluginstackai@gmail.com](mailto:pluginstackai@gmail.com).

This guide was first published on [PluginStack](https://www.pluginstackai.com/guides/add-mcp-server-to-vs-code/). Browse the [PluginStack directory](https://www.pluginstackai.com/) for more hand-checked MCP servers, plugins and setup guides.
