{"slug": "how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes", "title": "How to add an MCP server to VS Code (mcp.json, .mcp.json and fixes)", "summary": "A developer guide documents how VS Code's agent mode reads two distinct MCP configuration formats in 2026: the Copilot-style `mcpServers` key in `~/.copilot/mcp-config.json` or a workspace `.mcp.json`, and the VS Code-style `servers` key in `.vscode/mcp.json` or the user-profile `mcp.json`. The guide notes that the VS Code format remains the only place for input prompts, `envFile`, per-server sandboxing and development mode, and that copying a block between formats without renaming the top-level key is the most common setup error. It stresses that a saved config is not proof of a working connection — the server is confirmed only when a tool call returns real output.", "body_md": "Checked against the official docs: Oct 28, 2026\n\nVS Code's agents can call tools from MCP (Model Context Protocol) servers, for example to drive a browser, read current library docs or query GitHub. The setup changed in 2026: VS Code now has two config formats in different files, and the one you pick decides which features you get. This guide shows the quickest way to add a server, which file it ends up in, and what to check when the agent can't see it. It is based on Microsoft's VS Code documentation (checked 28 October 2026).\n\n`npx -y @playwright/mcp@latest`.` playwright`.\nMicrosoft'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.\n\nThis is where most confusion comes from. VS Code reads two formats, and they use different top-level keys:\n\n`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 `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.\nCopying 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.\n\nThe guided flow in the quick answer writes the file for you. Two extras are worth knowing:\n\n`@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.\nYou can also start from Chat: **Open Customizations**, then **MCP Servers**, then **Add Server**.\n\n`@mcp`.\nThe 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.\n\nA local server started with a command, here the [Playwright MCP server](https://www.pluginstackai.com/plugins/playwright-mcp/) (it needs Node.js 20 or newer). Full setup: [how to set up the Playwright MCP server](https://www.pluginstackai.com/guides/playwright-mcp-server-setup/):\n\n*.mcp.json (workspace root) or ~/.copilot/mcp-config.json*\n\n```\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    }\n  }\n}\n```\n\nA remote server only needs its URL. This is the [Context7](https://www.pluginstackai.com/plugins/context7/) endpoint from Microsoft's example; check the publisher's docs for sign-in and limits (for Context7, see [how to set up Context7 MCP](https://www.pluginstackai.com/guides/context7-mcp-setup/)). For the official GitHub server, including OAuth vs a personal access token, see [how to set up the GitHub MCP server](https://www.pluginstackai.com/guides/github-mcp-server-setup/):\n\n```\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.context7.com/mcp\"\n    }\n  }\n}\n```\n\nSame Playwright server, but note the `servers` key and the explicit `\"type\": \"stdio\"`:\n\n```\n{\n  \"servers\": {\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    }\n  }\n}\n```\n\nFor 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.\n\n*Adds the server to your VS Code user profile (VS Code format)*\n\n```\ncode --add-mcp '{\"name\":\"playwright\",\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp@latest\"]}'\n```\n\nThe two formats handle secrets differently:\n\n`${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. `${env:NAME}`, load a file with `inputs` entry so VS Code asks for the key the first time and stores it securely.\nAn input prompt, using the [Brave Search](https://www.pluginstackai.com/plugins/brave-search-mcp/) server's package and variable name:\n\n```\n{\n  \"inputs\": [\n    {\n      \"type\": \"promptString\",\n      \"id\": \"brave-key\",\n      \"description\": \"Brave Search API key\",\n      \"password\": true\n    }\n  ],\n  \"servers\": {\n    \"brave-search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave/brave-search-mcp-server\", \"--transport\", \"stdio\"],\n      \"env\": { \"BRAVE_API_KEY\": \"${input:brave-key}\" }\n    }\n  }\n}\n```\n\nA 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.\n\nThe `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](https://www.pluginstackai.com/guides/add-mcp-server-to-claude-desktop/).\n\nTo test, give the agent a harmless request that names the server, such as \"Use the Playwright MCP server to open [https://example.com](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.\n\n`mcp-config.json`).` PATH` or the runtime is missing or too old. Run the same command in a terminal to see the real error. On Windows, see `-d`. The container must stay in the foreground so VS Code can talk to it over stdio.\nThis guide is about connecting servers other people built. If you want to build your own MCP server, the (paid) [Agent Builder Rules + Prompts](https://www.pluginstackai.com/packs/) pack has Cursor and Claude Code rules, 2 Claude Code skills, 10 scaffolding prompts for TypeScript or Python, and 12 eval prompt templates. You don't need it just to add servers.\n\nFor 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.\n\nOn 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.\n\nThe 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](https://www.pluginstackai.com/guides/add-mcp-server-to-cursor/).\n\nCommands and config above come from these official docs. Tools change often, so check them for the latest steps.\n\nPluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email [pluginstackai@gmail.com](mailto:pluginstackai@gmail.com).\n\nThis guide was first published on [PluginStack](https://www.pluginstackai.com/guides/add-mcp-server-to-vs-code/). Browse the [PluginStack directory](https://www.pluginstackai.com/) for more hand-checked MCP servers, plugins and setup guides.", "url": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes", "canonical_source": "https://dev.to/pluginstackai/how-to-add-an-mcp-server-to-vs-code-mcpjson-mcpjson-and-fixes-1c9", "published_at": "2026-11-20 19:07:02+00:00", "updated_at": "2026-11-20 19:14:09.908143+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["VS Code", "Microsoft", "Model Context Protocol", "GitHub", "Playwright", "Context7", "Copilot"], "also_reported_by": [], "takeaway": "VS Code reads MCP servers from two incompatible formats — `mcpServers` in `.mcp.json`/`~/.copilot/mcp-config.json` versus `servers` in `.vscode/mcp.json`/profile `mcp.json` — so rename the top-level key when moving a block, and confirm the connection by calling a tool rather than trusting a saved co", "recommendation": {"advice": "When adding an MCP server to VS Code, match the top-level key to the file (`mcpServers` for `.mcp.json`, `servers` for `.vscode/mcp.json`) and verify by invoking a tool that returns real output.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes", "markdown": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes.md", "text": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes.txt", "jsonld": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-vs-code-mcp-json-mcp-json-and-fixes.jsonld"}}