retoor
251c3dc2ba
- 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)
55 lines
3.7 KiB
Markdown
55 lines
3.7 KiB
Markdown
# 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. |
|