How to add an MCP server to VS Code

Quick answer

1. Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run MCP: Add Server.
2. Pick HTTP if the publisher gave you a URL, or Command (stdio) if they gave you a command such as npx -y @playwright/mcp@latest.
3. Give it an ID you haven't used yet, such as playwright.
4. Choose where to save it: Global then Copilot Global for just you, or a workspace file to share it with your team.
5. Accept the trust or sign-in prompts you understand, then ask the agent to use the server and expand the tool call to confirm it really ran.

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.

Which config file is which

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

• Portable (Copilot) format, top-level 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 mcpServers shape Cursor and Claude Desktop use.
• VS Code format, top-level 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.

Option 1: MCP: Add Server

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

• From a package name: choose NPM Package, Pip Package or Docker Image and enter a name like @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.
• From another app: Add from another application... in the same picker finds servers you already configured elsewhere.

You can also start from Chat: Open Customizations, then MCP Servers, then Add Server.

Option 2: the MCP server gallery

1. Open the Extensions view (Ctrl+Shift+X or Cmd+Shift+X) and search for @mcp.
2. Select a server and read its publisher, capabilities and requirements.
3. Click Install for yourself, or right-click and choose Install in Workspace to share its config with the project.

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.

Option 3: write the config yourself

Portable format (.mcp.json or ~/.copilot/mcp-config.json)

A local server started with a command, here the Playwright MCP server (it needs Node.js 18 or newer):

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

A remote server only needs its URL. This is the Context7 endpoint from Microsoft's example; check the publisher's docs for sign-in and limits:

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

VS Code format (.vscode/mcp.json)

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.

From the command line

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

API keys and environment variables

The two formats handle secrets differently:

• Portable format: reference variables from the environment as ${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. envFile and input prompts are not supported here.
• VS Code format: reference variables as ${env:NAME}, load a file with envFile, or declare an inputs entry so VS Code asks for the key the first time and stores it securely.

An input prompt, using the Brave Search 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.

Reuse servers from Claude Desktop or Cursor

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.

Start, stop and check a server

• Run MCP: List Servers, pick the server, and choose Start, Stop, Restart or Show Output.
• Or use Chat: Open Customizations then MCP Servers: each server has an on/off toggle and a ... menu with the same actions.
• Disable is not the same as Stop: a disabled server doesn't start at all and its tools are unavailable until you turn it back on. Disabling only changes your own setup, not a shared config file.
• Run MCP: Reset Cached Tools if a server's tools changed but VS Code still shows the old list.

To test, give the agent a harmless request that names the server, such as "Use the Playwright MCP server to open 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.

Troubleshooting

• The server doesn't appear: check you edited the right file for the harness you are using, and that the top-level key matches the file (servers in .vscode/mcp.json, mcpServers in .mcp.json and mcp-config.json).
• A stdio server won't start: open Show Output for the server. Usually the command isn't on PATH or the runtime is missing or too old. Run the same command in a terminal to see the real error. On Windows, see Fix "spawn npx ENOENT"; for a server that starts and then exits, see MCP error -32000.
• Workspace servers never start: .vscode/mcp.json and .mcp.json follow Workspace Trust, so they don't run in Restricted Mode. Review the config before you trust a repository; stdio servers run code on your machine.
• A Docker server exits straight away: don't use -d. The container must stay in the foreground so VS Code can talk to it over stdio.
• An HTTP server won't connect or sign in: check the URL and your network, then follow the publisher's sign-in steps. In a company, an administrator may limit which MCP servers are allowed, and local config can't override that.
• The server runs but the agent never calls it: check it is enabled and its tools are selected for the session, then name the server explicitly in your prompt.
• It works locally but not in a dev container or over SSH: user-profile stdio servers run on your local machine. Configure the server in the remote environment (MCP: Open Remote User Configuration) and install its runtime there.

FAQ

Should I use .vscode/mcp.json or .mcp.json?

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.

Can I sandbox a server?

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.

Is it the same setup as Cursor?

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.