From 091100a4315b125650e65f6567256fce35d0d605 Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Mon, 11 May 2026 12:39:27 -0700 Subject: [PATCH 1/5] Document per-repo .mcp.json for Copilot CLI 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/docs#44234 --- .../customize-copilot/add-mcp-servers.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index b2807e1c71f9..31ded8c9166d 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -80,6 +80,38 @@ The following example shows a configuration file with a local server and a remot For more information on MCP server configuration, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp#writing-a-json-configuration-for-mcp-servers). +### Adding per-repository MCP servers + +You can configure MCP servers for a specific project by adding a JSON file to the repository. This is useful when you want servers to be available only when working in that project, or when you want to share an MCP setup with collaborators by committing it to the repository. + +{% data variables.copilot.copilot_cli_short %} reads project-level configuration from two locations: + +| Path | Recommended use | +|------|-----------------| +| `.mcp.json` at the project root | Local or per-checkout configuration | +| `.github/mcp.json` | Shared configuration that is committed to the repository | + +When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading every `.mcp.json` it finds along the way. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). + +The file format is the same as `~/.copilot/mcp-config.json`. For example: + +```json copy +{ + "mcpServers": { + "playwright": { + "type": "local", + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + } +} +``` + +> [!NOTE] +> * Project-level MCP servers are loaded only after you confirm folder trust on first launch. They are silently skipped in untrusted directories. For more information on folder trust, see [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli#trusted-directories). +> * In prompt mode (`copilot -p`), project-level MCP servers are not loaded by default. To enable them, set the `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` environment variable to `true`. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables). +> * VS Code's `.vscode/mcp.json` is not read by {% data variables.copilot.copilot_cli_short %}. It uses a different top-level key (`servers` rather than `mcpServers`). To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson). + ## Managing MCP servers You can manage your configured MCP servers using the following `/mcp` commands in {% data variables.copilot.copilot_cli_short %}. From 4751c8af057e61c343f4dbf5715d8d3841f1d96b Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Mon, 11 May 2026 12:58:37 -0700 Subject: [PATCH 2/5] Address review feedback - Clarify .mcp.json discovery is not limited to project root - Use prodname_vscode_shortname variable instead of hardcoding 'VS Code' --- .../how-tos/copilot-cli/customize-copilot/add-mcp-servers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index 31ded8c9166d..43911d21fb46 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -88,7 +88,7 @@ You can configure MCP servers for a specific project by adding a JSON file to th | Path | Recommended use | |------|-----------------| -| `.mcp.json` at the project root | Local or per-checkout configuration | +| `.mcp.json` (in any directory from your working directory up to the repository root) | Local or per-checkout configuration; commonly placed at the project root | | `.github/mcp.json` | Shared configuration that is committed to the repository | When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading every `.mcp.json` it finds along the way. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). @@ -110,7 +110,7 @@ The file format is the same as `~/.copilot/mcp-config.json`. For example: > [!NOTE] > * Project-level MCP servers are loaded only after you confirm folder trust on first launch. They are silently skipped in untrusted directories. For more information on folder trust, see [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli#trusted-directories). > * In prompt mode (`copilot -p`), project-level MCP servers are not loaded by default. To enable them, set the `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` environment variable to `true`. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables). -> * VS Code's `.vscode/mcp.json` is not read by {% data variables.copilot.copilot_cli_short %}. It uses a different top-level key (`servers` rather than `mcpServers`). To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson). +> * {% data variables.product.prodname_vscode_shortname %}'s `.vscode/mcp.json` is not read by {% data variables.copilot.copilot_cli_short %}. It uses a different top-level key (`servers` rather than `mcpServers`). To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson). ## Managing MCP servers From eb3250b86ace0fd688be7603f52dd7e90ced5148 Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Thu, 11 Jun 2026 16:46:06 -0400 Subject: [PATCH 3/5] Clarify Copilot CLI MCP config formats Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../how-tos/copilot-cli/customize-copilot/add-mcp-servers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index 43911d21fb46..6e38c65ff72b 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -93,7 +93,7 @@ You can configure MCP servers for a specific project by adding a JSON file to th When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading every `.mcp.json` it finds along the way. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). -The file format is the same as `~/.copilot/mcp-config.json`. For example: +Project-level files can use either the `mcpServers` top-level object shown in `~/.copilot/mcp-config.json`, or the bare top-level format where each key is an MCP server name, such as `{ "playwright": { ... } }`. For example: ```json copy { @@ -110,7 +110,7 @@ The file format is the same as `~/.copilot/mcp-config.json`. For example: > [!NOTE] > * Project-level MCP servers are loaded only after you confirm folder trust on first launch. They are silently skipped in untrusted directories. For more information on folder trust, see [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli#trusted-directories). > * In prompt mode (`copilot -p`), project-level MCP servers are not loaded by default. To enable them, set the `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` environment variable to `true`. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables). -> * {% data variables.product.prodname_vscode_shortname %}'s `.vscode/mcp.json` is not read by {% data variables.copilot.copilot_cli_short %}. It uses a different top-level key (`servers` rather than `mcpServers`). To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson). +> * {% data variables.product.prodname_vscode_shortname %}'s `.vscode/mcp.json` is not read by {% data variables.copilot.copilot_cli_short %}. It uses the unsupported top-level key `servers`. To migrate an existing `.vscode/mcp.json` to a format the CLI accepts, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson). ## Managing MCP servers From c6fd327f94ab63fe18032dfed70b906c1f2a9ad6 Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Thu, 11 Jun 2026 16:56:19 -0400 Subject: [PATCH 4/5] Add bare MCP config example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../customize-copilot/add-mcp-servers.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index 6e38c65ff72b..6459428906b5 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -84,16 +84,16 @@ For more information on MCP server configuration, see [AUTOTITLE](/copilot/how-t You can configure MCP servers for a specific project by adding a JSON file to the repository. This is useful when you want servers to be available only when working in that project, or when you want to share an MCP setup with collaborators by committing it to the repository. -{% data variables.copilot.copilot_cli_short %} reads project-level configuration from two locations: +{% data variables.copilot.copilot_cli_short %} looks for project-level configuration in the following locations: | Path | Recommended use | |------|-----------------| | `.mcp.json` (in any directory from your working directory up to the repository root) | Local or per-checkout configuration; commonly placed at the project root | | `.github/mcp.json` | Shared configuration that is committed to the repository | -When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading every `.mcp.json` it finds along the way. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). +When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading the first MCP configuration file it finds at each directory level. If both files exist in the same directory, `.mcp.json` takes precedence over `.github/mcp.json`. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). -Project-level files can use either the `mcpServers` top-level object shown in `~/.copilot/mcp-config.json`, or the bare top-level format where each key is an MCP server name, such as `{ "playwright": { ... } }`. For example: +Project-level files can use either the `mcpServers` top-level object shown in `~/.copilot/mcp-config.json`, or the bare top-level format where each key is an MCP server name. For example, this configuration uses the `mcpServers` object: ```json copy { @@ -107,6 +107,18 @@ Project-level files can use either the `mcpServers` top-level object shown in `~ } ``` +The same server can also be configured with the bare top-level format: + +```json copy +{ + "playwright": { + "type": "local", + "command": "npx", + "args": ["@playwright/mcp@latest"] + } +} +``` + > [!NOTE] > * Project-level MCP servers are loaded only after you confirm folder trust on first launch. They are silently skipped in untrusted directories. For more information on folder trust, see [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli#trusted-directories). > * In prompt mode (`copilot -p`), project-level MCP servers are not loaded by default. To enable them, set the `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` environment variable to `true`. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables). From bd40ec93b3d9b3b9b1451bc6dff26fc4c61c551d Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Thu, 11 Jun 2026 16:59:28 -0400 Subject: [PATCH 5/5] Clarify MCP config precedence wording Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../how-tos/copilot-cli/customize-copilot/add-mcp-servers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index 6459428906b5..cf5d27e8832b 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -91,7 +91,7 @@ You can configure MCP servers for a specific project by adding a JSON file to th | `.mcp.json` (in any directory from your working directory up to the repository root) | Local or per-checkout configuration; commonly placed at the project root | | `.github/mcp.json` | Shared configuration that is committed to the repository | -When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading the first MCP configuration file it finds at each directory level. If both files exist in the same directory, `.mcp.json` takes precedence over `.github/mcp.json`. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). +When you start {% data variables.copilot.copilot_cli_short %} inside a Git repository, the CLI walks from your current working directory up to the repository root, loading MCP configuration files along the way. If both `.mcp.json` and `.github/mcp.json` exist in the same directory, `.mcp.json` takes precedence. When server names conflict, definitions in files closer to your working directory take precedence. Project-level definitions also take precedence over those in `~/.copilot/mcp-config.json`. For more information on relative trust, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels). Project-level files can use either the `mcpServers` top-level object shown in `~/.copilot/mcp-config.json`, or the bare top-level format where each key is an MCP server name. For example, this configuration uses the `mcpServers` object: