John Lancaster
124 lines
4.7 KiB
Markdown
124 lines
4.7 KiB
Markdown
# 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)
|