VS Code MCP Servers: mcp.json, Inputs and Agent Setup
Updated 2026-11-18
To add an MCP server to VS Code, run MCP: Add Server from the Command Palette, or write a .vscode/mcp.json file with a servers object. Each server has a type (stdio, http or sse). Once it is running, Chat can call the server's tools.
Guided setup
The fastest route is the Command Palette. Run MCP: Add Server and pick how the server runs:
- HTTP (HTTP or Server-Sent Events): enter the endpoint URL and a unique server ID. The VS Code docs use
https://learn.microsoft.com/api/mcpwith the IDmicrosoftLearnas the example. - Command (stdio): enter the launch command. The docs example is
npx -y @playwright/mcp@latest, which needs Node.js 18 or newer.
You can also open Chat: Open Customizations, go to MCP Servers and select Add Server. MCP: Browse MCP Servers opens server discovery.
Write .vscode/mcp.json by hand
For a workspace you share with a team, a config file is easier to review. The editor-managed format uses a top-level servers key (not mcpServers). A local server:
{
"servers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}
A remote server:
{
"servers": {
"microsoftLearn": {
"type": "http",
"url": "https://learn.microsoft.com/api/mcp"
}
}
}
The type field
| type | Meaning | Key fields |
|---|---|---|
stdio | A local process | command (required), args, env, envFile |
http | Streamable HTTP | url (required), headers |
sse | Legacy Server-Sent Events | url (required), headers |
The docs say to prefer http when the server supports it. For stdio, command must be on your system path or be a full path. env values can be strings, numbers or null. envFile points to an env file, for example "${workspaceFolder}/.env". For OAuth with a fixed client, an HTTP server accepts an oauth object with a clientId property.
Keep secrets out with inputs
Do not paste API keys into mcp.json. Declare an input, then reference it as ${input:id}. VS Code prompts for the value the first time the server starts and stores it securely.
{
"inputs": [
{
"type": "promptString",
"id": "perplexity-key",
"description": "Perplexity API Key",
"password": true
}
],
"servers": {
"perplexity": {
"type": "stdio",
"command": "npx",
"args": ["-y", "your-mcp-server-package"],
"env": {
"PERPLEXITY_API_KEY": "${input:perplexity-key}"
}
}
}
}
Input types are promptString (free text, with password to hide typing and an optional default), pickString (a list of options) and command (runs a command to get the value). You can use ${input:id} in env and in headers, for example "Authorization": "Bearer ${input:api-key}" on an HTTP server. The package name in the example above is a placeholder. Use the one your server documents.
Newer portable format
The current VS Code reference describes a second format, which it recommends for new Copilot setups. It uses mcpServers instead of servers, and lives in one of these files:
~/.copilot/mcp-config.json(or$COPILOT_HOME/mcp-config.json) for your user..mcp.jsonin the workspace root, when the experimentalchat.mcp.workspaceRootConfig.enabledsetting is on.
{
"mcpServers": {
"context7": {
"type": "http",
"url": "https://mcp.context7.com/mcp",
"tools": ["*"]
}
}
}
The portable format does not support ${input:...}. Use ${NAME} or ${NAME:-default} environment-variable references instead. The reference labels the servers format as the editor-managed format for the Local harness, which it marks deprecated. Check the MCP configuration reference to see which format your VS Code version expects.
Use the tools in Chat
With a server running, ask for a task that needs it. Chat picks relevant tools, so you do not need to name the server. To test the connection, name it once and ask for something harmless. The VS Code docs suggest a prompt like this for the Microsoft Learn server:
Use the Microsoft Learn MCP tools to find the official documentation for the Kusto Query Language where operator. Summarize its syntax and link to the documentation. Do not change files.
Expand the tool call in the chat to see what was sent and what came back. In the current docs, set the Session Target dropdown to Copilot for the user-level setup. Chat runs MCP tools through its agent, which many guides call agent mode. Look for the agent option in the Chat view if your version words it differently.
Manage and troubleshoot
- MCP: List Servers shows each server and its actions: Show Output, Restart Server, Stop Server.
- Show Output opens that server's output channel, which is where startup errors appear.
- MCP: Reset Trust clears editor-managed trust decisions. It does not reset Workspace Trust.
- Workspace
.vscode/mcp.jsonand.mcp.jsonfiles inherit Workspace Trust. In Restricted Mode these servers cannot start. - Settings Sync covers the user-profile
mcp.json, not workspace files.
Trust and review
A stdio server runs code on your machine. Review the publisher, the command or endpoint, and the access it asks for before you trust a repository's config. Do not type passwords or API keys into server-initiated input forms. Use the inputs mechanism above. More on this in the MCP server security checklist.
Looking for something to connect? Browse MCP servers that work with VS Code, such as the Cloudflare MCP server. Using other tools too? See the guides for Cursor and Claude Code.
Sources
- Add and use MCP servers in VS Code - code.visualstudio.com
- MCP configuration reference - code.visualstudio.com
- Manage MCP servers in VS Code - code.visualstudio.com
FAQ
Where do I configure MCP servers in VS Code?
Run MCP: Add Server from the Command Palette for a guided flow, or write a .vscode/mcp.json file in your workspace. A user-profile mcp.json holds servers shared across workspaces.
What does the type field mean in VS Code mcp.json?
type is stdio for a local process started with command and args, http for a Streamable HTTP endpoint, or sse for a legacy Server-Sent Events endpoint. Both http and sse use a url.
How do I keep API keys out of mcp.json in VS Code?
Declare an entry in the inputs array with type promptString and password true, then reference it as ${input:id}. VS Code prompts on first start and stores the value securely.
Why will my workspace MCP server not start?
Workspace mcp.json files inherit Workspace Trust. In Restricted Mode these servers cannot start. Trust the workspace, or run MCP: Reset Trust to clear earlier decisions.