Files

T

retoor 251c3dc2ba research: mcp-client-support subject (106 sources, 3 conclusions)

- wire spec: lifecycle, stdio + Streamable HTTP transports, tools,
  utilities, legacy SSE, versioning, changelog (14 Tier 1)
- client ecosystem: Claude Code/VS Code/Cursor/Codex configs,
  mcp-remote, Smithery, registries, Glama (12 Tier 1)
- security/ops: authorization draft, trust model, poisoning,
  rug pulls, production hardening (12 Tier 1) + 68 Tier 2 cards
- conclusions: minimal stdlib client on 2025-11-25, normalizer +
  resolver agent for pasted configs/GitHub URLs, untrusted-until-
  consent trust model; nothing built yet
- audit PASS (14 subjects, 797 sources, 32 conclusions)

2026-10-18 19:23:02 +02:00

3.7 KiB

Raw Blame History

VS Code: Add and manage MCP servers

Metadata

Field	Value
Institute	Molodetz Institute - Research and Retrieval Division
Subject	mcp-client-support
Document type	Source Dossier
Tier	1
Source title	Add and manage MCP servers
Source URL	https://code.visualstudio.com/docs/agent-customization/mcp-servers
Source publisher / author	Microsoft
Source type	vendor docs
Source date (published)	Unknown, not stated (living doc)
Date researched	2026-10-18
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	gather-subagent direct page fetch, parent synthesis from evidence pack
Confidence	High
Status	Active

Summary

Microsoft's task-oriented VS Code documentation for adding and managing MCP servers. It establishes four config locations split across two wrapper keys (mcpServers in .mcp.json/mcp-config.json, servers in .vscode/mcp.json/profile), declares the mcpServers destinations the portable converged future, and documents auto-discovery from other apps, an MCP server gallery, and enable/disable state stored separately from shared config files.

Key findings

Four config locations: workspace .mcp.json (top-level mcpServers, "Preferred for configurations that you share with your team"), workspace .vscode/mcp.json (top-level servers, for "input variables, development mode, and per-server sandboxing"), user $COPILOT_HOME/mcp-config.json (fallback ~/.copilot/mcp-config.json, mcpServers), profile mcp.json (servers).
"The flow also lists the deprecated .vscode/mcp.json and VS Code user-profile destinations for compatibility. Prefer the portable destinations for new servers": .mcp.json/mcp-config.json with mcpServers is the converged future.
Same server entry works under either wrapper key; docs show identical {"type": "http", "url": ...} and {"command": "npx", "args": [...]} examples under mcpServers and under servers.
Auto-discovery: "VS Code can automatically detect and reuse MCP server configurations from supported applications" (sources include Claude Desktop, GitHub Copilot CLI, Cursor, Windsurf); also an MCP server gallery via Extensions @mcp and an "MCP: Add Server" guided flow.
"You can enable or disable an MCP server globally or for a specific workspace... The enable/disable state is stored separately from the server configuration in mcp.json, so it does not affect shared configuration files."

Pros / strengths

States the convergence direction explicitly (prefer portable mcpServers destinations), which resolves the two-wrapper-key ambiguity for tooling.
Documents server entries as wrapper-agnostic with identical examples under both keys, so importers can treat the keys as interchangeable at the entry level.
Auto-discovery from named rival apps (Claude Desktop, Cursor, Windsurf) is itself evidence of a de facto shared config shape.

Cons / limitations / caveats

Living doc with no publish date; the deprecation status of .vscode/mcp.json could shift without a version marker.
Whether VS Code supports ${env:VAR} interpolation is unresolved: only seen in an unopened mirror's table, while Microsoft's own pages document ${input:} and envFile.
Page originally requested at /docs/copilot/customization/mcp-servers redirected to /docs/agent-customization/mcp-servers, so older links rot.

Relevance to tai

Establishes the two-wrapper-key reality (mcpServers vs servers) that tai's importer must accept on input and the portable mcpServers form it should emit. The ${input:}/envFile secret idioms need translation when resolving VS Code configs for other clients.

Changelog

Date	Change
2026-10-18	Initial dossier created.

3.7 KiB Raw Blame History