Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
loganrosen wants to merge 2 commits into
base: main
Choose a base branch
from
+32 −0
Open

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
091100a
Document per-repo .mcp.json for Copilot CLI
loganrosen May 11, 2026
4751c8a
Address review feedback
loganrosen May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` (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).

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).
> * {% 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

You can manage your configured MCP servers using the following `/mcp` commands in {% data variables.copilot.copilot_cli_short %}.
Expand Down
Loading