Connect an MCP server

The system that knows the consumers of your team’s shared library (the one other services import) is a service registry. It already has an MCP server (a tool service speaking the Model Context Protocol - a standard way for Copilot and other agents to call external systems) - most internal platforms ship one now, or it is a thin process someone on your platform team wrote. Your job is not to build the server; it is to tell Copilot the server exists and how to reach it. That is a single file.

The file: .vscode/mcp.json

Workspace-level MCP servers live in .vscode/mcp.json at the root of your repo. It holds a servers object - one key per server, each describing how Copilot should connect:

{
  "servers": {
    "service-registry": {
      "type": "http",
      "url": "https://registry.internal.example.com/mcp"
    }
  }
}

The keys you set depend on how the server runs:

• type - either "stdio" (Copilot launches the server as a local process and talks to it over standard in/out) or "http" (Copilot connects to a server already running at a URL). The registry is a shared internal service, so it is http.
• command and args - for a stdio server, the executable to launch and the arguments to pass it. A registry server you run locally might be "command": "npx" with "args": ["-y", "@yourco/registry-mcp"].
• url - for an http server, where it lives.

Because .vscode/mcp.json sits in the repo, it is shareable: commit it and every teammate who opens the repo gets the same registry connection without setting anything up. The reach becomes part of the project, not a thing each person rigs by hand.

Four ways to add one

You rarely hand-write the JSON from scratch. VS Code gives you four on-ramps (routes and commands per the VS Code MCP documentation, verified September 2026); the first three write the same .vscode/mcp.json, while a dev container declares its own copy:

1. “MCP: Add Server” from the Command Palette - a guided flow that asks what kind of server you are adding and writes the entry for you.
2. The Extensions view, filtered with @mcp - browse servers the way you browse extensions, install one with a click.
3. Editing mcp.json directly - once you know the shape, often fastest, and the source of truth the other routes write into.
4. devcontainer.json, under customizations.vscode.mcp - if your repo uses a dev container, declare the server there so it is present the moment the container builds.

Beyond this workspace

Some servers are not repo-specific - a server you personally use across every project does not belong in one repo’s .vscode/mcp.json. For those, run “MCP: Open User Configuration” and add them at the user level. They follow you between workspaces instead of being committed to one. The registry stays at the workspace level, because it is this work’s reach; a personal server lives at the user level.

Whichever level a server lives at, it is not free once connected: its tool definitions ride into the model’s context on every request (unless your client defers schemas), used or not. One registry that closes a real gap earns its cost; a browse-and-install habit stacks up definitions that crowd the window before you have asked anything. Mount and unmount below and watch what each server costs (the gauge’s window size and built-in-tools baseline are illustrative of one model class; check your model):

82k of 200k (41%) spent before your first message

Built-in tools (12k, fixed)MCP tool schemas (70k)

Defer schemas until first use - each server shrinks to a ~0.4k stub (name + description); the full schema loads only when a tool is actually called. Availability and thresholds are client- and configuration-dependent, so check yours before budgeting around it.

• GitHub35 tools · 26kIssues, PRs, reviews, workflows - big surface, big schema.
• Browser (Playwright)25 tools · 18kNavigate, click, fill, screenshot, network inspection.
• Notion15 tools · 11kSearch, fetch, create and update pages and databases.
• Figma12 tools · 9kRead frames, components, and design tokens.
• Postgres8 tools · 6kQuery, schema inspection, explain plans.

Tool counts and schema sizes are illustrative (~600 - 800 tokens per tool definition). The shape is the point: every enabled server's schemas are paid for in window space - up front on clients that load eagerly, at first use on clients that defer.

Try it

Add a simple MCP server to .vscode/mcp.json - a filesystem or search server from the MCP servers documentation works well for a first try. Ask Copilot a question that requires that server’s tools to answer. Confirm the trust prompt (Copilot’s ask-before-start confirmation, covered next lesson) appears before the server starts; if it connects silently, either you already approved it or your config skipped the gate.

Add the service-registry entry, and VS Code notices the new server. But it will not connect yet - not until you say it is safe. Next: trust before it runs.