How to control MCP servers in GitHub Copilot
To control MCP servers in GitHub Copilot, turn on the “MCP servers in Copilot” policy first. Then choose one allowlist method: a registry in “Registry only” mode (public preview), or an allowlist in managed-settings.json (generally available). The Copilot cloud agent has its own repository setting and does not use the registry restriction.
Map each control to its layer
Copilot has four places to set MCP rules, and each covers a different surface. Set the policy at enterprise level for uniform access, then add organization policies only where teams differ.
| Control | Where it lives | What it covers | Plan and status |
|---|---|---|---|
| MCP servers in Copilot | Enterprise: AI controls, then MCP. Organization: Settings, Copilot, Policies | Whether MCP servers can run at all. Applies to IDEs, cloud agent, third-party agents, CLI, Copilot app and code review. Not Chat in GitHub or Spark | Business and Enterprise seats. The cloud agent page says it is disabled by default |
| Restrict MCP access to registry servers, with MCP Registry URL | Same menus, MCP section | Allow all, or Registry only. Applies to IDEs, CLI and Copilot app. Not the cloud agent | Public preview. The docs call it not the recommended method |
managed-settings.json with allowedMcpServers and deniedMcpServers |
Enterprise settings file, usually in a .github-private repository, or MDM |
Allow and deny by serverUrl or serverCommand. Docs say client coverage will expand |
Generally available |
| Cloud agent MCP servers | Repository settings on GitHub.com, set by repository administrators | MCP servers the cloud agent loads. Shared with code review. Separate from CLI project config files | Requires the MCP policy. The registry restriction does not apply |
Turn on the MCP servers policy
Nothing else in this list works until the base policy is on. The docs recommend keeping it enabled, and you can limit servers to an approved list on top of it.
- Open the enterprise policy at AI controls, then MCP. For a single organization, open Settings, then Copilot, then Policies, and find the MCP section under Features.
- Set “MCP servers in Copilot” to Enabled everywhere at enterprise level, or Enabled for an organization.
- Confirm the policy applies to the seats you care about. Copilot Free, Pro, Pro+ and Max users are not governed by it, so their MCP use needs a different control.
- Save. The docs say the policy applies immediately to developers.
Choose registry-only mode or a managed allowlist
The two methods overlap. The registry is simpler to start with, but the managed file is the stronger control. GitHub’s own docs say the custom registry has weaker enforcement than managed-settings.json, and that its matching is by name or ID only.
Registry-only mode (public preview)
Host an MCP registry that matches the MCP specification and serves HTTPS. Then enter its URL in the MCP Registry URL field and set “Restrict MCP access to registry servers” to Registry only. Azure API Center users should enter the base URL only. Adding /v0.1/servers makes the registry error, because Copilot adds that path itself.
The registry restriction is enforced in these clients, at the minimum versions the docs list:
| Client | Minimum version |
|---|---|
| Copilot CLI | 1.0.11 |
| VS Code | 1.109.3 |
| JetBrains | 1.5.64 |
| Visual Studio | 18.4.0 |
| Eclipse | 4.38 |
| Xcode | 0.47.0 |
| Copilot cloud agent | Not supported |
The managed-settings allowlist (generally available)
The managed-settings.json file takes two keys, allowedMcpServers and deniedMcpServers. Each entry matches a remote server by serverUrl, with * wildcards, or a local server by serverCommand, an exact command and argument list. Prefer those two over matching by name. GitHub’s registry docs note that enforcement based only on server name or ID “can be bypassed by editing configuration files”, and they point to managed-settings.json for URL-based enforcement that users can’t override locally.
{
"allowedMcpServers": [
{ "serverUrl": "https://api.githubcopilot.com/*" },
{ "serverCommand": ["npx", "@playwright/mcp@latest"] }
],
"deniedMcpServers": [
{ "serverUrl": "https://untrusted.example/*" }
]
}Evaluation order and fail-closed behavior
The client checks each server in a fixed order. The docs list it as follows.
- Always allow the built-in default servers, such as the GitHub MCP server.
- Block the server if it matches any
deniedMcpServersentry. - If
allowedMcpServersis present, block the server unless it matches an entry. - Block the server if its URL or command contains an unresolved variable, such as
${VARIABLE}.
When several managed sources apply, a server must pass every layer that defines a list. A malformed list is treated as an empty allowlist, which blocks everything except the built-in defaults. If a retrieval fails, the client keeps the last policy it enforced. The docs say the effective policy can only get stricter.
Control the cloud agent in repository settings
The cloud agent does not read the registry or the managed allowlist for its MCP servers. Repository administrators set them in the repository settings on GitHub.com. The same settings apply to Copilot code review, and they are separate from the project config files that Copilot CLI reads.
Out of the box, the cloud agent starts with two servers, GitHub and Playwright. The GitHub server uses a token scoped to read-only access on the current repository. Access to other repositories needs credentials you configure yourself. Playwright can reach only localhost and 127.0.0.1 inside the agent’s environment.
The docs also list three limits you should plan around. The cloud agent supports MCP tools only, not resources or prompts. It does not support remote servers that use OAuth. It does not ask for approval before it calls a tool.
Watch the gaps
Four limits matter most when you plan a rollout.
- Registry checks can be bypassed. GitHub says registry enforcement is based on name or ID matching, which users can get around by editing configuration files.
- Strict blocking is not available yet. The docs say enforcement that stops non-registry servers from installing is not yet available.
- The cloud agent sits outside the registry. Registry-only mode does not cover it, so use the repository setting.
- Free and Pro users are outside the policy. The MCP policy applies only to Business and Enterprise seats.
Test each rule with a harmless server before you enforce it, and check which servers a developer’s client actually loads after the change.
Enforcing this with AIControls
The Copilot policies above decide which MCP servers load. AIControls is a separate layer that governs the model traffic from your tools. It supports Copilot in VS Code, and it provides per-user tokens and per-user and per-session cost and budget limits. Keep the GitHub policies in place alongside it, because AIControls does not replace the server allowlist. Download AIControls to run it in your own cluster.
Next steps
Turn on the MCP policy, then pick one allowlist method. Use managed-settings.json for the stronger control, and add the registry only if you already run one. Set the cloud agent’s servers in repository settings, because the registry does not reach it. For the wider picture, read MCP security and governance for AI coding agents. For the identity side of agent access, see Okta cross app access for AI agents, and for gateway options, read the AI gateway buyer’s guide.
Frequently asked questions
Which policy must be enabled before GitHub Copilot can use MCP servers?
The MCP servers in Copilot policy. If you are a member of an organization or enterprise on a Copilot Business or Copilot Enterprise plan, the policy must be enabled before you can use MCP with Copilot. Copilot Free, Pro, Pro+ and Max users are not governed by this policy. The cloud agent page says the policy is disabled by default, so check its state before you roll out.
What is the difference between registry-only mode and managed-settings.json in Copilot?
Registry-only mode checks servers against a registry you host, and it is in public preview. Its matching is by name or ID, and users can bypass it by editing configuration files. managed-settings.json holds allowedMcpServers and deniedMcpServers, matches by URL or exact command, and is generally available. GitHub's docs recommend it over the registry for stricter enforcement.
Does the MCP registry restriction apply to the Copilot cloud agent?
No. The supported-surfaces table shows that Restrict MCP access to registry servers applies to IDEs, Copilot CLI and the Copilot app. The cloud agent is not in the enforcement list. Control the cloud agent's MCP servers with the repository setting that repository administrators manage on GitHub.com.
Can a Copilot user add an MCP server that the allowlist does not list?
The docs say a server must pass every policy layer that defines a list, and a deny match from any source blocks it. A malformed list is treated as an empty allowlist, which blocks all servers except the built-in defaults. Registry-only mode alone does not stop a user from installing a non-registry server, because GitHub says strict enforcement is not yet available.