Adding an MCP server to VS Code

Where the config lives

VS Code stores MCP server definitions in an mcp.json file. There are two scopes:

Workspace: a .vscode/mcp.json file at the root of your project. Commit it to share servers with your team. Open it from the Command Palette with "MCP: Open Workspace Folder Configuration".

User profile (global): a user-level mcp.json that applies across all your projects. Open it with the "MCP: Open User Configuration" command.

Run "MCP: List Servers" from the Command Palette at any time to see, start, stop, and inspect configured servers. MCP tools surface inside GitHub Copilot Chat when you switch the chat into Agent mode.

The exact JSON key: "servers" (not "mcpServers")

The single most common setup mistake is the top-level key. VS Code uses "servers". Cursor and Claude Desktop use "mcpServers". If you copy a config from one of those tools without renaming the key, VS Code silently ignores it.

The mcp.json file has up to three top-level sections: "servers" (the map of server name to config), "inputs" (placeholders for secrets, see below), and an optional "sandbox" section that restricts file-system and network access on macOS and Linux.

Each entry under "servers" is keyed by a name you choose. Remote servers set "type": "http" and a "url". Local servers set a "command" and "args" and speak over stdio; for stdio the "type" field is optional.

Minimal config and CLI examples

A workspace .vscode/mcp.json with one remote (HTTP) server and one local (stdio) server:

{ "servers": { "my-remote": { "type": "http", "url": "<url>" }, "my-local": { "command": "<command>", "args": ["<arg>"] } } }

Prefer a guided flow? Open the Command Palette and run "MCP: Add Server", then pick HTTP or stdio and the install scope (workspace or global).

From a terminal you can add a server in one shot. The JSON must be escaped for your shell:

code --add-mcp "{\"name\":\"my-local\",\"command\":\"<command>\",\"args\":[\"<arg>\"]}"

By default this targets your user profile. Prefix it with --folder-uri <path> (for example, code --folder-uri <path> --add-mcp "...") to write to a specific workspace's .vscode/mcp.json instead.

Never hardcode secrets: use "inputs"

Do not paste API keys or tokens directly into mcp.json, especially a workspace file you might commit. VS Code provides the "inputs" array, which prompts you for a value (optionally masked) and injects it at runtime via the ${input:<id>} reference.

{ "inputs": [ { "type": "promptString", "id": "api-key", "description": "Your API key", "password": true } ], "servers": { "my-remote": { "type": "http", "url": "<url>", "headers": { "Authorization": "Bearer ${input:api-key}" } } } }

This keeps the secret out of source control and out of the server config itself.

Vet the server before you add it

Adding an MCP server is not like installing a passive library. Once registered, its tools become callable by Copilot's Agent mode and run with your local machine's access, your environment variables, and any credentials you wire in. A local stdio server runs arbitrary commands on your machine; a remote HTTP server receives whatever your agent sends it.

Before adding any server, confirm a few things. Who publishes it, and is the source public and inspectable? For a local server, what command and package does it actually run (npx, uvx, docker) and from where? For a remote server, what URL and provider sits behind it, and over what transport? Do the tool descriptions or schemas ask for more than the job needs, or carry hidden instructions? Does it want secrets, and are those scoped to the minimum?

These are exactly the failure modes that bite MCP setups: tool poisoning (malicious instructions hidden in a tool's schema or description), command injection, hardcoded or over-broad secrets, and the lethal trifecta of private data access, untrusted content, and an exfiltration path combined in one agent. Treat a new server like granting an app full access to your dev environment, because that is effectively what it is.

Adding an MCP server to VS Code — FAQ

Related