VS Code mcp.json: Adding MCP Servers Step by Step

To add an MCP server to VS Code, you have three routes. Search @mcp in the Extensions view and install one from the gallery; run “MCP: Add Server” from the Command Palette and follow the guided flow; or write the entry yourself in an mcp.json file. A workspace file lives at .vscode/mcp.json with a top-level servers object; your personal one opens with “MCP: Open User Configuration”. A local server is an entry with "type": "stdio" and a command; a remote one is "type": "http" and a url. VS Code then starts the server, lists its tools under Configure Tools in the chat input, and hands them to the agent. One thing changed this year: chat now runs through agent harnesses, and not every harness reads every server, so the last step is checking the one you use can see it.

This guide is the setup, step by step. Whether to trust a server, the approval before each tool call, auto-approve and how to keep secrets out of the file are covered in VS Code MCP security; read it before you commit a workspace file. For other editors and apps, see which apps support MCP.

Before you start: is MCP switched on?

VS Code’s own quickstart goes straight to the gallery, with no switch to turn on first. In an organisation, though, MCP can be restricted. The chat.mcp.access setting takes three values, all, registry (only servers from a configured registry) and none, and an administrator can fix it by policy. On Copilot Business or Enterprise there is also GitHub’s own MCP policy, which is off until an admin enables it. If the gallery is empty or “MCP: Add Server” is missing, that is the first thing to check, and it is not something you can change from your own settings.

Step 1: choose where the server goes

The VS Code MCP servers guide↗ (opens in a new tab) names three places, and the choice decides who gets the server:

• .vscode/mcp.json in the project, using servers. Commit it and everyone who opens the repository gets the same servers.
• .mcp.json at the project root, using mcpServers, the key most other clients use. VS Code calls this the portable format, and it matters for agent harnesses, below.
• Your user profile, opened with “MCP: Open User Configuration”. Servers there are available in every workspace you open, and each VS Code profile can have its own.

Step 2: the quick routes

From the gallery

1. Open the Extensions view and type @mcp in the search box. The MCP server gallery lists what is available; select one to read its details page.
2. Select Install to add it to your user profile, or right-click and choose Install in Workspace to write it into .vscode/mcp.json.
3. When VS Code asks, confirm you trust the server. It starts, VS Code discovers its tools, and they appear in chat.

From the Command Palette

Run “MCP: Add Server”. A guided flow takes you through the server’s details, asks whether it goes in Workspace or Global (your user profile), and writes the entry for you. There is also a command-line route, code --add-mcp, which takes the server as a JSON string and adds it to your user profile.

Step 3: write the entry by hand

Writing the file yourself is the route to use when a vendor’s documentation gives you the values, or when you want the file under review. The MCP configuration reference↗ (opens in a new tab) defines three top-level keys: servers, an optional inputs array, and an optional sandbox object for sandboxed local servers on macOS and Linux. VS Code gives you IntelliSense while you type. A file with one remote and one local server looks like this:

{
  "inputs": [
    {
      "type": "pickString",
      "id": "log-level",
      "description": "Log level for the docs server",
      "options": ["info", "debug"]
    }
  ],
  "servers": {
    "fenbs": {
      "type": "http",
      "url": "https://fenbs.ai/api/mcp"
    },
    "docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@your-org/docs-mcp@2.3.1"],
      "cwd": "${workspaceFolder}",
      "env": { "LOG_LEVEL": "${input:log-level}" }
    }
  }
}

• A remote server needs type (http, or sse for an older server) and url. Optional headers send fixed HTTP headers, and oauth holds OAuth settings; for most servers you leave it out and VS Code opens a browser sign-in the first time the server is used.
• A local server needs type: "stdio" and command. args is the argument list, cwd the working folder (the workspace by default), env sets environment variables and envFile loads more from a file.
• The server name is the key, such as fenbs or docs. The reference suggests camelCase, no spaces, unique, and something that says what the server does.
• Pin the version in args for a package-run server, so the code that starts tomorrow is the code you read today.

Inputs and variables

An input is a value VS Code asks for instead of storing it in the file. Declare it in inputs with an id, then reference it as ${input:id} anywhere in a server entry. There are three types: promptString for free text, pickString for a choice from a list, as above, and command to take the value from a VS Code command. The file also understands predefined variables such as ${workspaceFolder} and ${userHome}, and environment variables as ${env:NAME}. For API keys, use a promptString with password set to true; why, and the alternatives, are in the security guide linked above.

Step 4: start, stop and restart

Servers start in one of three ways. Open mcp.json and use the inline actions (code lenses) above each entry. Right-click the server under MCP SERVERS - INSTALLED in the Extensions view. Or run “MCP: List Servers”, pick the server and choose an action, which is also where Show Output lives when something fails.

You often do not need to start anything. With the experimental chat.mcp.autostart setting at its default, newAndOutdated, VS Code starts servers that have never run, or whose configuration has changed, when you send a chat message; onlyNew and never are the other values. Disabling a server, from the same menus, keeps it from starting and removes its tools from chat. That state is stored apart from mcp.json, so turning a shared server off for yourself does not change the committed file.

• “MCP: Reset Cached Tools” clears the tool list VS Code remembers, for a server whose tools changed.
• A dev object on an entry, with watch set to a glob, restarts the server when its source files change; debug attaches a debugger to a Node.js or Python stdio server. Useful when you are building one.

Step 5: pick the tools

Select Configure Tools in the chat input to see every tool each server offers, and switch individual tools or whole servers on and off. Leave on only what the task needs. Servers can offer more than tools. Resources are attached from Add Context, then MCP Resources, or with “MCP: Browse Resources”; prompts are typed as /server.prompt in the chat input; and MCP Apps appear inline when a server has them. What each of those is: tools, resources and prompts.

Which agent harness sees your servers

VS Code no longer has a single chat agent. It supports Local, GitHub Copilot, Anthropic Claude and OpenAI Codex harnesses↗ (opens in a new tab), plus a Cloud target, chosen with the Session Target control. The documentation is specific about MCP for some of them:

• Local runs in the extension host and can use MCP servers alongside VS Code’s built-in and extension tools. Everything in this guide applies.
• Copilot runs on the Copilot SDK in the Agent Host, and its sessions can currently reach only local MCP servers that do not require authentication. A remote server with a sign-in will not appear there; use Local for it.
• Cloud sessions use the MCP servers configured by the cloud service, not your mcp.json.
• Claude and Codex: the harness page does not list MCP rules for either. Test before relying on a server there.

The Agent Host↗ (opens in a new tab) also reads MCP configuration differently. It does not read .vscode/mcp.json itself. It reads the portable .mcp.json in the workspace and ~/.copilot/mcp-config.json for the user, and VS Code forwards the servers you configured in VS Code to it, except servers that need interactive input such as ${input:...} variables. So a server that depends on an input works in a Local session and silently disappears from an Agent Host one. If you want one file that every harness and the Copilot CLI read, use .mcp.json with mcpServers. Note that setting chat.mcp.autostart to never does not stop an Agent Host session starting its servers.

When a server does not show up

• Look for the error indicator in the Chat view and choose Show Output, or run “MCP: List Servers”, pick the server and choose Show Output. Common causes are a wrong command, a missing runtime such as Node.js, or a typo in the URL.
• Check the file uses the right key: servers in .vscode/mcp.json, mcpServers in .mcp.json. A block copied from another client’s documentation often has the wrong one.
• Check the harness, as above, and that the server’s tools are ticked under Configure Tools.
• Check the workspace is trusted. Workspace servers do not start in Restricted Mode.
• To test the server outside VS Code, the MCP Inspector shows its tools and lets you call them by hand.

VS Code can also pick up servers you configured elsewhere. With chat.mcp.discovery.enabled, it discovers configurations from Claude Desktop, GitHub Copilot CLI, Cursor and Windsurf, which is now Devin Desktop↗ (opens in a new tab). Every source is off by default. If a server appears that you never added, this is where it came from.

Adding a task board

fenbs, a task board where people and AI assistants are members with roles, is the fenbs entry in the example above: an http server at https://fenbs.ai/api/mcp with no key in the file. The first time it is used, VS Code opens fenbs in your browser; you sign in, tick what the assistant may do (reading is always on; adding and changing tasks, and commenting, are your choice) and approve. Commit the file and each person who opens the repository signs in as themselves, with their own role on the board as the ceiling. Because it needs a sign-in, use it from a Local session today, not a Copilot one. Every change it makes is recorded in History with the assistant’s name. The steps are on the GitHub Copilot integration page.