Based on GitHub / Microsoft’s official docs, checked October 20, 2026

How to add an MCP server to GitHub Copilot in VS Code

Agent mode in VS Code can call tools from MCP servers. You can add a server from the MCP gallery, through the MCP: Add Server command, or by editing a JSON file. The detail that trips people up: VS Code’s own mcp.json uses a top-level "servers" key, while the portable Copilot and .mcp.json files use "mcpServers". This guide follows the VS Code documentation as checked on October 20, 2026.

1. 1. Open MCP: Add Server

   Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run MCP: Add Server. Choose HTTP if the publisher gives you a server URL, or Command (stdio) if it gives you a launch command. The Playwright example below uses a command.

   npx -y @playwright/mcp@latest

2. 2. Pick an ID and where to store it

   Enter a server ID that is not already used, such as playwright. For a personal setup, choose Global and then Copilot Global, which writes $COPILOT_HOME/mcp-config.json (or ~/.copilot/mcp-config.json). For a team setup, pick a workspace destination instead (see the table of locations below).

3. 3. Or install from the MCP gallery

   Type @mcp in the Extensions view search box, or run MCP: Add Server > Browse MCP Servers.... Select Install for a personal install, or right-click and choose Install in Workspace to share the configuration with the project. Your organization can restrict which servers appear.

4. 4. Or write the VS Code mcp.json yourself

   In the VS Code format the servers live under "servers", and each stdio server needs "type": "stdio" and a "command". Run MCP: Open Workspace Folder MCP Configuration to open .vscode/mcp.json, or MCP: Open User Configuration for your profile file.

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

5. 5. Add a remote (HTTP) server

   For a hosted server use "type": "http" and a "url". Add "headers" for token auth. VS Code also accepts "sse" for older servers, and "oauth": { "clientId": ... } when a provider needs a pre-registered OAuth client.

   {
     "servers": {
       "example": {
         "type": "http",
         "url": "https://mcp.example.com/mcp"
       }
     }
   }

6. 6. Trust it and check a tool call

   Review the trust and sign-in prompts before accepting them. Then open Chat in agent mode, check that the server’s tools are listed in the tools picker, and ask for something that needs one of them. MCP: List Servers shows each server with start, stop, restart and Show Output actions.

"servers" vs "mcpServers": which key goes where

VS Code’s documentation describes two formats. The VS Code format (.vscode/mcp.json and the user-profile mcp.json) uses a top-level "servers" object, plus optional "inputs" and "sandbox" objects. The portable format used by ~/.copilot/mcp-config.json and a workspace-root .mcp.json uses a top-level "mcpServers" object.

The docs warn not to copy a configuration from one to the other without checking the format. Portable files don’t support VS Code input variables or envFile. If you paste a Cursor or Claude Desktop snippet that starts with "mcpServers" into .vscode/mcp.json, rename the key to "servers" and add a "type" to each server.

Where VS Code stores MCP configuration

Copilot Global: $COPILOT_HOME/mcp-config.json, or ~/.copilot/mcp-config.json when COPILOT_HOME is unset. Personal, portable format ("mcpServers").

Workspace root: .mcp.json. Shared with the team and with other compatible Copilot tools. MCP: Add Server only offers this destination when the experimental chat.mcp.workspaceRootConfig.enabled setting is on, but existing .mcp.json files are still read when it’s off.

Workspace .vscode/mcp.json and the user-profile mcp.json: VS Code format ("servers"). Use these when you need input variables or per-server sandboxing. The guided flow now labels them deprecated, but they still work for compatibility.

Discovery: chat.mcp.discovery.enabled lets VS Code reuse servers already configured in other apps, such as Claude Desktop, the Copilot CLI, Cursor and Windsurf.

Keep API keys out of the file with input variables

In the VS Code format you can declare "inputs" and reference them as ${input:id}. VS Code prompts for the value the first time the server starts and stores it securely. The input types are promptString, pickString and command; set "password": true to hide what you type. The example below is the one from the VS Code reference.

Servers that need interactive ${input:...} values are not forwarded to Copilot harness sessions, so keep those in the VS Code format.

{
  "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}" }
    }
  }
}

Add a server from the command line

The code CLI can add a server to your user profile with --add-mcp and a JSON description of the server:

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

If the server does not show up

Run MCP: List Servers and open Show Output for the server to see its startup log. If its tools changed, run MCP: Reset Cached Tools. If you declined a trust prompt for a server from outside the workspace, MCP: Reset Trust clears that decision; workspace servers follow Workspace Trust instead.

Check the key name first. A file with "mcpServers" in .vscode/mcp.json, or "servers" in .mcp.json, is the most common format mix-up. If the gallery or a server is missing, your organization may be limiting access with the chat.mcp.access setting.

Tips

• Use distinct server IDs when you run several servers together.
• Never paste credentials into chat or commit them; use input variables, envFile, or the publisher’s sign-in flow.
• "dev": { "watch": ... } restarts a server you are developing when its files change.
• A remote HTTP server doesn’t need Node.js installed locally; a stdio server started with npx does.

Next steps

Sources

• https://code.visualstudio.com/docs/agent-customization/mcp-servers · checked 2026-10-20
• https://code.visualstudio.com/docs/agents/reference/mcp-configuration · checked 2026-10-20