VS Code mcp.json Setup in 2026: .vscode/mcp.json, .mcp.json and Copilot Global

In VS Code today, the recommended way to add an MCP server is the guided flow: run MCP: Add Server from the Command Palette, enter a URL or command, and pick a destination. For personal use, Microsoft's docs point you to Global > Copilot Global, which writes to ~/.copilot/mcp-config.json. The older .vscode/mcp.json file still works, but the guided flow now labels it deprecated.

That change matters because the two kinds of file use different formats. Copilot's portable files use a top-level mcpServers object. The VS Code format, used in .vscode/mcp.json, uses servers. This guide explains which file to use, shows valid examples of each and covers how to check a server works.

Checked against: Microsoft's Add MCP servers in VS Code, MCP configuration reference and Manage MCP servers pages on 2 November 2026.

Which file should you use?

Microsoft's docs map each goal to a destination:

VS Code now runs agents through different "harnesses." The configuration reference says Copilot harness sessions "read the portable format directly" and that "the agent doesn't read .vscode/mcp.json directly." If a server in .vscode/mcp.json seems invisible in a Copilot session, this is the likely reason.

Add a server with the guided flow

1. Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run MCP: Add Server.
2. Choose HTTP (HTTP or Server-Sent Events) for a URL, or Command (stdio) for a launch command.
3. Enter the URL or command. For Microsoft's Playwright example, the command is npx -y @playwright/mcp@latest, which needs Node.js 18 or newer.
4. Enter a unique server ID, such as playwright.
5. Pick Global > Copilot Global for personal use, or a workspace destination to share.
6. Review any trust or sign-in prompts before accepting them.

You can also start from Chat: Open Customizations > MCP Servers > Add Server, or browse the MCP server gallery (Preview) by searching @mcp in the Extensions view.

Example: portable format (Copilot Global or .mcp.json)

From Microsoft's configuration reference, a local stdio server:

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

And a remote HTTP server:

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

For variables, the portable format uses ${NAME} or ${NAME:-default}. The docs say portable files "don't support VS Code input variables or environment files."

Example: VS Code format (.vscode/mcp.json)

The same Playwright server in the VS Code format uses servers and an explicit type:

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

The VS Code format's main advantage is inputs. This example from the reference prompts for an API key the first time the server starts and hides what you type:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

The VS Code format uses ${env:NAME} for environment variables and supports envFile. All four blocks were checked against Microsoft's reference on 2 November 2026. You can also add a server from a terminal with code --add-mcp '{"name":"playwright","type":"stdio","command":"npx","args":["-y","@playwright/mcp@latest"]}'.

Sandboxing (macOS and Linux)

In the VS Code format, a stdio server can run in a sandbox that limits file and network access. The docs say "sandboxing is available on macOS and Linux only," and that when it is on, "tool confirmations are auto-approved because the server runs in a controlled environment." Set "sandboxEnabled": true and list allowed paths and domains in the server's sandbox object.

Verify the server works

Microsoft's docs warn that "adding a configuration isn't proof that the agent can use the server." Their three checks:

1. A tool from the intended server was called in your session.
2. It returned output without a connection error.
3. The agent's answer reflects that output.

To see logs, open the server's ... menu in the MCP Servers section, or run MCP: List Servers, and choose Show Output. Restart a server from the same menu after changing its config. Run MCP: Reset Trust if you need to re-review a server you trusted earlier.

Common mistakes

• Pasting a Claude Desktop or Cursor block into .vscode/mcp.json. Those use mcpServers; this file needs servers.
• Using ${input:...} in a portable file. Inputs only work in the VS Code format.
• Expecting Settings Sync to copy everything. The docs say sync covers "the user-profile mcp.json, not workspace .mcp.json files or the Copilot user mcp-config.json."
• Forgetting organization policy. "Local configuration can't override organizational restrictions." On Copilot Business or Enterprise, an admin may need to enable MCP first.

Next step

Pick a first server from our best MCP servers for VS Code list, then follow a specific guide such as connecting VS Code to GitHub. Our GitHub Copilot MCP setup guide covers the org policy, and the config generator can draft either format.

Frequently asked questions