### What article(s) on docs.github.com is this issue about? - `/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers` (primary) - `/copilot/how-tos/use-copilot-agents/use-copilot-cli` — "Add an MCP server" section ### What is currently incorrect or missing? The how-to pages only document `~/.copilot/mcp-config.json` and the interactive `/mcp add` flow. Users looking for "per-repository MCP config" have no path from these pages to the workspace-level configuration that Copilot CLI actually supports. The behaviour is partially covered in the reference pages (`cli-config-dir-reference.md`, `cli-command-reference.md`), but the how-to never links to it and never mentions `.mcp.json` at all. Specifically, the how-to does not document: 1. **Workspace config file locations** — `.mcp.json` at cwd, and `.github/mcp.json`. The CLI also walks from cwd up to the git root, loading every `.mcp.json` it finds (closer-to-cwd wins). 2. **Supported formats** — both `{ "mcpServers": {...} }` and the Claude-style bare `{ "name": {...} }` are accepted. (VS Code's `{ "servers": {...} }` is *not* — this is a frequent source of confusion, e.g. github/copilot-cli#3083.) 3. **Folder-trust gating** — workspace MCP servers are silently skipped until the folder is trusted (either via the first-launch prompt or by appearing in `trustedFolders`). 4. **Prompt-mode (`-p`) opt-out** — in non-interactive mode, workspace `.mcp.json` is **not** loaded by default. Users must set `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true`. This env var is listed in `cli-command-reference.md` but never connected back to `.mcp.json` in any how-to. ### Suggested fix Add a "Workspace (per-repository) MCP servers" subsection to `add-mcp-servers.md` (and a pointer from `use-copilot-cli.md`) covering: - File locations and lookup order - Supported JSON formats with examples (including the bare Claude-style form) - Folder-trust requirement and what happens on first launch from an untrusted directory - A note that `-p` mode requires `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true`, with a link to the env-var reference - Migration recipe from `.vscode/mcp.json` (already exists in the reference page — just link to it) ### Additional context Related issues in `github/copilot-cli` whose root cause is partly documentation: - github/copilot-cli#1886 — `.github/mcp.json` reported as not working; reporter notes "documented as though they should work" - github/copilot-cli#3083 — `.mcp.json` not loading; user's config uses the unsupported `"servers"` key - github/copilot-cli#3126 — SDK twin of the prompt-mode `includeWorkspaceSources` default