MCP server in VS Code

How VS Code discovers MCP servers

VS Code checks two locations for MCP server configurations, in priority order:

Workspace-scoped servers in .vscode/mcp.json only activate when the workspace is trusted (the VS Code Workspace Trust prompt). User-scoped servers in settings.json are available in all trusted workspaces. If the same server name appears in both locations, the workspace configuration wins.

VS Code sends an initialize JSON-RPC request to each configured server at startup and when you run MCP: Restart Server. It then calls tools/list to build the tool registry. The registry is refreshed automatically when the server sends a notifications/tools/list_changed notification — you do not need to restart VS Code when your tool list changes dynamically.

.vscode/mcp.json configuration format

The configuration file uses a servers object where each key is the server's display name in VS Code:

{
  "servers": {
    "my-api-tools": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    },
    "local-dev-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    },
    "local-stdio-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

The configuration supports three server types:

For HTTP servers, VS Code includes Mcp-Session-Id headers on subsequent requests after the initialize handshake completes. Your server must echo the session ID in its response headers and route subsequent requests to the correct session context.

Injecting secrets with input variables

Do not put API keys in .vscode/mcp.json — the file is committed to git. VS Code supports input variable substitution that prompts the developer once and stores the value in the VS Code secret storage:

{
  "inputs": [
    {
      "id": "my-api-key",
      "type": "promptString",
      "description": "API key for my-api-tools server",
      "password": true
    }
  ],
  "servers": {
    "my-api-tools": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:my-api-key}"
      }
    },
    "local-stdio-server": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "DATABASE_URL": "${input:database-url}",
        "API_SECRET": "${input:my-api-key}"
      }
    }
  }
}

When VS Code first connects to a server that uses ${input:…} variables, it prompts the developer for each value. The values are stored in VS Code's encrypted secret storage (via OS keychain on macOS/Windows, libsecret on Linux). Subsequent workspace opens do not re-prompt unless the developer clears the secrets via MCP: Clear Stored Inputs from the Command Palette.

For stdio servers, the environment variables set in env are merged with VS Code's process environment. This means PATH, HOME, and other shell environment variables are available to the subprocess without explicit configuration — useful if your stdio server spawns child processes that need the developer's shell environment.

Tool invocation in Copilot Chat agent mode

MCP tools appear in GitHub Copilot Chat when the chat is in agent mode. You enter agent mode by selecting the @workspace agent or choosing a custom MCP server agent from the agent picker. The tool selection dropdown (the tools button, with a tools-wrench icon) shows all tools from all connected MCP servers.

Copilot Chat invokes MCP tools by generating a tools/call JSON-RPC request with the tool name and arguments derived from the LLM's response. The tool call goes through an approval step:

Tools that modify files, call external APIs, or run shell commands should never be permanently allowed — the approval step is the last line of defense before an LLM-generated tool call executes. Your MCP server should implement tool annotations (readOnlyHint, destructiveHint) to signal the risk level to VS Code, which uses them to color-code the approval prompt.

The tool result is returned inline in the chat thread. If your tool returns content with type: "text", VS Code renders the text in the chat message. If the tool returns type: "image", VS Code renders the image inline. If the tool sets isError: true, Copilot Chat shows the error and may ask the user to try a different approach.

Debugging MCP connections in VS Code

The Output panel shows every JSON-RPC message exchanged with each MCP server. Open it with View → Output, then select MCP: <server-name> from the dropdown:

[2026-06-26 14:23:01] → initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "Visual Studio Code", "version": "1.99.3" },
    "capabilities": { "sampling": {} }
  }
}

[2026-06-26 14:23:01] ← initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "my-api-tools", "version": "1.2.0" },
    "capabilities": { "tools": {} }
  }
}

[2026-06-26 14:23:01] → notifications/initialized
{}

[2026-06-26 14:23:01] → tools/list
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

[2026-06-26 14:23:01] ← tools/list
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      { "name": "search_docs", "description": "Search documentation", "inputSchema": { ... } },
      { "name": "create_issue", "description": "Create a new issue", "inputSchema": { ... } }
    ]
  }
}

Common failure patterns visible in the Output panel:

For stdio servers, the Output panel also shows stderr from the subprocess. Print diagnostic messages to stderr from your MCP server — they appear in the VS Code Output panel without interfering with the JSON-RPC protocol on stdout.

Per-workspace vs user-level server configuration

Choosing between workspace and user scope affects security, portability, and sharing:

The recommended pattern for team-shared MCP servers: put the server URL and non-secret configuration in .vscode/mcp.json (committed), and use ${input:…} variables for any secrets. Each developer is prompted once for their API key; after that, VS Code handles credential storage securely.

Add .vscode/mcp.json.example to your repository showing the structure with placeholder values, and add .vscode/mcp.json to .gitignore only if the configuration itself contains workspace-specific values that differ per developer. If all developers use the same server URL, commit the file.

Monitoring MCP servers that VS Code users depend on

When a team commits an MCP server to .vscode/mcp.json, every developer who opens the workspace connects to that server. A server outage silently breaks Copilot Chat tool calls for the entire team — VS Code shows "Tool unavailable" in the chat without explaining that the server is down vs the tool failed.

The monitoring gap is similar to Lambda: VS Code only sees the tool call result, not the underlying protocol health. An MCP server can return HTTP 200 on a liveness endpoint while the initialize handshake fails or tools/list returns an empty array — VS Code users experience this as "Copilot can't find any tools" with no error message.

AliveMCP runs a full protocol probe — initialize + tools/list + a sentinel tool call — every 60 seconds. When the probe fails, you get an alert before the first developer opens their VS Code and wonders why their MCP tools stopped working. Add your MCP server URL to AliveMCP monitoring as part of your server's deployment checklist.

Further reading

• MCP server with GitHub Copilot — agent mode tool configuration
• MCP server in Cursor — configuring MCP tools for AI-assisted development
• MCP server in Claude Desktop — claude_desktop_config.json setup
• MCP server in Zed editor — context_servers configuration
• MCP tool annotations — readOnlyHint, destructiveHint, and idempotentHint
• Debugging MCP servers — protocol traces, inspector, and runtime errors
• AliveMCP — continuous protocol monitoring for MCP servers