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. v1.0.40 no longer loads mcp servers from ./.mcp.json on start up 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/lsp.json and .github/mcp.json do not work copilot-cli#1886 — .github/mcp.json reported as not working; reporter notes "documented as though they should work"
• v1.0.40 no longer loads mcp servers from ./.mcp.json on start up copilot-cli#3083 — .mcp.json not loading; user's config uses the unsupported "servers" key
• resolveDiscoveredConfig does not read workspace .mcp.json — includeWorkspaceSources never set copilot-cli#3126 — SDK twin of the prompt-mode includeWorkspaceSources default