Skip to content
agents.cli

Connect an MCP server

The system that knows shared-lib’s consumers is your team’s service registry. It already has an MCP server — most internal platforms ship one now, or it’s a thin process someone on your platform team wrote. Your job isn’t to build the server; it’s to tell Copilot the server exists and how to reach it. That’s a single file.

The file: .vscode/mcp.json

Section titled “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 to it:

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

The keys you’ll 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’s 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. That’s the case here.

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

Four ways to add one

Section titled “Four ways to add one”

You rarely hand-write the JSON from scratch. VS Code gives you four on-ramps, and they all land in the same place:

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

Beyond this workspace

Section titled “Beyond this workspace”

Some servers aren’t repo-specific — a server you personally use across every project doesn’t 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’s this work’s reach; a personal server lives at the user level.

Whichever level a server lives at, it isn’t free once connected: its tool definitions ride into the model’s context on every request, 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’ve asked anything. Mount and unmount below and watch what each server costs:

82k of 200k (41%) spent before your first message
Built-in tools (12k, fixed)MCP tool schemas (70k)

Tool counts and schema sizes are illustrative (~600–800 tokens per tool definition). The shape is the point: every registered server is paid for in window space whether the session uses it or not.

Add the service-registry entry, and VS Code will notice the new server. But it won’t connect to it yet — not until you say it’s safe. Next: trust before it runs.