Agents Index

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:

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

typeMeaningKey fields
stdioA local processcommand (required), args, env, envFile
httpStreamable HTTPurl (required), headers
sseLegacy Server-Sent Eventsurl (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:

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

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

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.

More guides