vscode config improvements

2026-06-20 18:05:05 -05:00
parent c73771c2f4
commit 38edc4ac36
5 changed files with 169 additions and 14 deletions
@@ -0,0 +1,123 @@
+# Configure MCP Servers in VS Code
+
+Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope).
+
+## Where Configuration Lives
+
+VS Code supports two MCP configuration locations:
+
+- Workspace scope: `.vscode/mcp.json` in the repository.
+- User profile scope: open with the `MCP: Open User Configuration` command.
+
+Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers.
+
+## Minimal mcp.json
+
+```json
+{
+  "servers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp"
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@microsoft/mcp-server-playwright"]
+    }
+  }
+}
+```
+
+The `servers` object keys are logical server names shown in VS Code MCP management surfaces.
+
+## Add Servers Through VS Code UI
+
+1. Run `MCP: Add Server` from the Command Palette.
+2. Choose Workspace or Global target.
+3. Review generated config in `mcp.json`.
+4. Start or restart the server from `MCP: List Servers`.
+
+This guided flow is usually safer than manual edits when onboarding teammates.
+
+## Security and Secrets
+
+1. Do not hardcode tokens or API keys in `mcp.json`.
+2. Prefer input variables or environment-file patterns supported by the MCP configuration schema.
+3. Start only trusted servers, because local servers can execute code on your machine.
+4. Use trust prompts as a checkpoint instead of bypassing review.
+
+## Security Best Practices
+
+1. Apply least privilege by default.
+2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration.
+3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files.
+4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled.
+5. Use one server per trust boundary instead of one large multi-purpose server.
+6. Review server `command` and `args` as code during pull requests.
+7. Disable or uninstall unused MCP servers to reduce attack surface.
+8. Use HTTPS endpoints for remote MCP servers whenever available.
+9. Pin server packages or versions where practical to avoid accidental supply-chain drift.
+10. Reset trust and re-review configuration after major server changes.
+
+### Operational Guardrails
+
+1. Treat MCP resources as publishable unless an explicit access control layer exists.
+2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect.
+3. Define ownership for each server entry, including who approves changes and who rotates secrets.
+4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout.
+
+### Team Review Checklist
+
+Use this checklist before merging workspace MCP configuration changes:
+
+1. No plaintext secrets in `mcp.json`.
+2. `command` and `args` are from trusted publishers and expected binaries.
+3. Server scope is correct (workspace vs user profile).
+4. Sandboxing is enabled for local `stdio` servers when supported.
+5. Sandbox allowlists are narrow (minimum paths and domains).
+6. The change includes an owner and rollback path.
+
+## Sandbox Local stdio Servers (Linux/macOS)
+
+For local `stdio` servers, enable sandboxing when possible:
+
+```json
+{
+  "servers": {
+    "myServer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "sandboxEnabled": true
+    }
+  },
+  "sandbox": {
+    "filesystem": {
+      "allowWrite": ["${workspaceFolder}"]
+    },
+    "network": {
+      "allowedDomains": ["api.example.com"]
+    }
+  }
+}
+```
+
+Sandboxing is currently available on Linux and macOS, not Windows.
+
+## Troubleshooting Checklist
+
+1. Open server logs from `MCP: List Servers` -> `Show Output`.
+2. Confirm trust state (or run `MCP: Reset Trust` if needed).
+3. Confirm server command and arguments run outside VS Code.
+4. Confirm workspace-vs-user scope matches where you expect the server to run.
+5. If using remote development, configure the server in the remote scope when needed.
+
+## Source Documentation
+
+- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data)
+- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration)
+- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security)
+- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro)