Skip to content

Document per-repo .mcp.json for Copilot CLI#44236

Open
loganrosen wants to merge 2 commits into
github:mainfrom
loganrosen:copilot-cli-document-per-repo-mcp-json
Open

Document per-repo .mcp.json for Copilot CLI#44236
loganrosen wants to merge 2 commits into
github:mainfrom
loganrosen:copilot-cli-document-per-repo-mcp-json

Conversation

@loganrosen
Copy link
Copy Markdown
Contributor

@loganrosen loganrosen commented May 11, 2026

Why:

Closes #44234

The Copilot CLI MCP how-to (add-mcp-servers.md) only documents the user-level ~/.copilot/mcp-config.json and the interactive /mcp add flow. The CLI also reads per-repository configuration from .mcp.json and .github/mcp.json, but neither this how-to nor the "Add an MCP server" section of use-copilot-cli.md mentions those files at all. The relevant trust and prompt-mode behaviours live only in the reference pages and are not linked from the how-to.

This has produced several related bug reports in github/copilot-cli whose root cause is partly documentation — see #44234 for the list.

What's being changed:

Adds a new ### Adding per-repository MCP servers subsection to content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md covering:

  • The .mcp.json (project root) and .github/mcp.json file locations, with their recommended uses.
  • Lookup behaviour: the CLI walks from the current working directory up to the Git repository root, loading every .mcp.json it finds; closer-to-cwd wins on name conflicts; project-level definitions take precedence over ~/.copilot/mcp-config.json.
  • A minimal JSON example pointing back at the existing format.
  • A note that workspace MCP servers are loaded only after folder trust is confirmed.
  • A note that in prompt mode (copilot -p) workspace MCP servers are not loaded by default, and require setting GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true. This connects the env var (already in the reference) back to .mcp.json for the first time.
  • A clarification that .vscode/mcp.json is not read, pointing to the existing migration recipe.

All claims were verified against Copilot CLI v1.0.44-2 (the bundled JS) and confirmed by running copilot mcp list and copilot -p in both modes.

Check off the following:

@loganrosen
Document per-repo .mcp.json for Copilot CLI
091100a 
Adds a 'Adding per-repository MCP servers' subsection to the Copilot
CLI MCP how-to page, covering:

- The .mcp.json (project root) and .github/mcp.json file locations
- Lookup behavior (walk from cwd up to the git root; closer files win)
- Folder trust gating
- Prompt mode (-p) opt-out and the
  GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP environment variable
- Pointer to the existing .vscode/mcp.json migration recipe

Refs: github#44234
Copilot AI review requested due to automatic review settings May 11, 2026 19:42
@github-actions github-actions Bot added the triage Do not begin working on this issue until triaged by the team label May 11, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 11, 2026 •
edited
Loading

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source Review Production What Changed
copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md fpt
ghec
 fpt
ghec

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

Copilot AI reviewed May 11, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds documentation to the Copilot CLI MCP how-to explaining how to configure MCP servers per-repository using .mcp.json / .github/mcp.json, including precedence rules and prompt-mode / trust-related behavior.

Changes:

  • Documented per-repository MCP configuration file locations (.mcp.json and .github/mcp.json) and precedence over user config.
  • Added an example per-repo MCP JSON config and notes about folder trust and prompt mode (copilot -p) behavior.
  • Clarified that VS Code’s .vscode/mcp.json is not consumed by Copilot CLI and linked to migration guidance.

Comment thread content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md Outdated
Comment thread content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md Outdated
@loganrosen
Address review feedback
4751c8a 
- Clarify .mcp.json discovery is not limited to project root
- Use prodname_vscode_shortname variable instead of hardcoding 'VS Code'
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

triage Do not begin working on this issue until triaged by the team

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document per-repo .mcp.json / .github/mcp.json and prompt-mode gating for Copilot CLI

2 participants

@loganrosen