Skip to content

Commit d3d21e7

Browse files
docs-botdocs-bot
authored
Merge pull request #40360 from github/repo-sync
Repo sync
2 parents 4a5a17d + 9e237d4 commit d3d21e7

File tree

2 files changed

+201
-0
lines changed

2 files changed

+201
-0
lines changed

‎content/copilot/how-tos/administer-copilot/configure-mcp-server-access.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: Configure MCP server access for your organization or enterprise
3+
intro: You can configure an MCP Registry URL and access control policy to determine which MCP servers developers can discover and use in supported IDEs with {% data variables.product.prodname_copilot %}.
4+
permissions: Enterprise owners and organization owners
5+
product: '{% data variables.copilot.copilot_enterprise_short %} or {% data variables.copilot.copilot_business_short %}'
6+
versions:
7+
feature: copilot
8+
allowTitleToDifferFromFilename: true
9+
topics:
10+
- Copilot
11+
- Enterprise
12+
shortTitle: Configure MCP server access
13+
contentType: how-tos
14+
---
15+
16+
> [!NOTE]
17+
> * The display of available MCP servers based on a configured MCP registry is supported in {% data variables.product.prodname_vscode_shortname %} Stable and Insiders.
18+
> * Policy enforcement for the "Registry only" setting is currently available only in {% data variables.product.prodname_vscode_shortname %} Insiders, with support for {% data variables.product.prodname_vscode_shortname %} Stable coming in October 2025. MCP registry and allowlisting support is coming to all other Copilot IDEs in the coming months.
19+
20+
## Overview
21+
22+
An MCP registry is a directory of Model Context Protocol (MCP) servers that acts like a catalog for IDEs and {% data variables.product.prodname_copilot_short %} (as well as other host applications). Each registry entry points to a server's manifest, which describes the tools, resources, and prompts that the server exposes.
23+
24+
As an enterprise or organization owner, you can configure an **MCP Registry URL** along with an access control policy to determine which MCP servers your developers can see and run in supported IDEs with {% data variables.product.prodname_copilot %}.
25+
26+
By configuring an MCP Registry, you can:
27+
* **Provide a curated catalog** of MCP servers your developers can discover and use
28+
* **Restrict access** to unapproved servers for more granular access control
29+
* **Give clarity to developers** when a server is blocked by policy
30+
31+
If you don't have an MCP registry set up yet, see [Setting up an MCP Registry](#setting-up-an-mcp-registry) later in this article.
32+
33+
## About MCP policy settings
34+
35+
The following settings let you control how MCP servers are discovered and accessed in your organization or enterprise.
36+
37+
### MCP servers policy
38+
39+
First, you must set the overall **MCP servers in Copilot** policy:
40+
* Enabled: MCP servers are allowed (default behavior depends on registry configuration)
41+
* Disabled: No MCP servers can be used by any users with Copilot seats from this enterprise or organization
42+
* No policy (Enterprise only): Child organizations can set their own MCP policies
43+
44+
### MCP Registry URL
45+
46+
The **MCP Registry URL** is an optional field where you specify the endpoint of your discoverable or restricted internal MCP registry.
47+
48+
When configured:
49+
* The servers listed in the registry are displayed in IDEs that support MCP
50+
* Enables the "Restrict MCP access to registry servers" option
51+
52+
### "Restrict MCP access to registry servers" setting
53+
54+
Under the **Restrict MCP access to registry servers** setting, you choose how strictly to enforce registry-based access:
55+
56+
* **Allow all** (default): Developers can run any local and remote MCP servers. Registry servers are still shown in the IDE catalog as a curated list for easier discoverability.
57+
* **Registry only**: Developers can only run MCP servers that are explicitly listed in the uploaded MCP registry. All other servers—whether remote (hosted) or local (running client-side on the user's machine)—will be blocked at runtime. In IDE UIs, blocked servers appear greyed out with a warning message. In the `mcp.json` configuration file, they may also show `"run": "blocked"`.
58+
59+
> [!WARNING]
60+
> * You cannot configure the "Registry only" option without providing an MCP registry URL with a valid format and clicking "Save".
61+
> * "Registry only" enforcement is currently active **only** in {% data variables.product.prodname_vscode_shortname %} Insiders. Support for other Copilot environments is being added in the coming months.
62+
63+
## Configuring the MCP allowlist policy for an enterprise
64+
65+
{% data reusables.enterprise-accounts.access-enterprise %}
66+
{% data reusables.enterprise-accounts.policies-tab %}
67+
{% data reusables.enterprise-accounts.copilot-tab %}
68+
{% data reusables.enterprise-accounts.copilot-policies-tab %}
69+
1. Under "Features", ensure **MCP servers in {% data variables.product.prodname_copilot_short %}** is set to **Enabled**.
70+
1. In the **MCP Registry URL (optional)** field, enter the URL of your specification-compliant MCP registry.
71+
1. Click **Save**.
72+
1. Next to **Restrict MCP access to registry servers**, select one of the following from the dropdown:
73+
* **Allow all**: No restrictions. All MCP servers can be used.
74+
* **Registry only**: Only servers from the registry may run.
75+
76+
> [!NOTE]
77+
> If no registry URL is set, the "Registry only" option blocks all MCP servers.
78+
79+
Your chosen policy will immediately apply to developers in your enterprise.
80+
81+
## Configuring the MCP allowlist policy for an organization
82+
83+
{% data reusables.profile.access_org %}
84+
{% data reusables.profile.org_settings %}
85+
1. In the sidebar, under "Code, planning, and automation", click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} {% data variables.product.prodname_copilot_short %}**, then click **Policies**.
86+
1. Under "Features" ensure **MCP servers in {% data variables.product.prodname_copilot_short %}** is set to **Enabled**.
87+
1. In the **MCP Registry URL (optional)** field, enter the URL of your specification-compliant MCP registry.
88+
1. Click **Save**.
89+
1. Next to **Restrict MCP access to registry servers**, select one of the following from the dropdown:
90+
* **Allow all**: No restrictions. All MCP servers can be used.
91+
* **Registry only**: Only servers from the registry may run.
92+
93+
> [!NOTE]
94+
> If no registry URL is set, the "Registry only" option blocks all MCP servers.
95+
96+
Your chosen policy will immediately apply to developers in your organization.
97+
98+
## How are MCP allowlists enforced?
99+
100+
{% data variables.product.github %} uses the following strategies for MCP allowlist enforcement.
101+
102+
### Local servers
103+
104+
MCP allowlist enforcement applies to local MCP servers as well. When "Registry only" is configured, local servers must be included in the registry to be allowed.
105+
106+
**Including local servers in your registry:**
107+
* Local servers must be listed in your registry with their correct server ID
108+
* The server ID must match exactly between the registry entry and the installed server
109+
* Consult the server's documentation or manifest for its canonical ID
110+
* For consistent deployment across your organization, provide installation instructions that ensure users install the server with the expected ID
111+
112+
### Policy resolution for users with multiple seats
113+
114+
MCP allowlist enforcement is always tied to the organization or enterprise that assigns the {% data variables.product.prodname_copilot %} seat. If a user has multiple seats (for example, from several organizations or from both an enterprise and its child organizations), {% data variables.product.github %} automatically resolves conflicts and applies a single active policy.
115+
116+
The resolution logic is:
117+
118+
1. **Scope**: Policies set by a parent enterprise override those set by an organization. Enterprise policies trickle down to all organizations and members within that enterprise.
119+
1. **Enforcement strictness**: `Registry only` outranks `Allow all`.
120+
1. **Recency of registry upload**: If two policies have the same scope and strictness, the registry most recently uploaded (saved) wins.
121+
1. **Tie-breaker**: If all else is equal, the lowest internal ID wins (rare edge case).
122+
123+
> [!IMPORTANT]
124+
> At this time, only one registry URL can be applied to a user. Even if multiple organizations or enterprises provide different registries, only the winning registry (determined by the above rules) is used.
125+
>
126+
> **Recommendation**: To ensure consistency and avoid conflicts across multiple organizations, set and maintain your MCP registry URL and allowlist policy at the **enterprise** level whenever possible.
127+
128+
## Setting up an MCP Registry
129+
130+
If you don't already have an MCP Registry configured, there are a few different ways you can create one depending on your needs.
131+
132+
### Simple/static registry
133+
134+
At its core, a registry is just an HTTPS endpoint that serves a list of MCP server manifests. You can publish this as a static JSON file on {% data variables.product.prodname_pages %}, an S3 bucket, or any web server. This is the fastest and most lightweight option.
135+
136+
### Example registry format
137+
138+
Your registry must return a JSON response with the following structure:
139+
140+
``` json
141+
{
142+
"servers": [
143+
{
144+
"id": "github",
145+
"name": "GitHub MCP Server",
146+
"description": "Tools and resources for GitHub repos, issues, PRs, and Actions.",
147+
"manifest_url": "https://registry.yourcompany.com/servers/github/manifest.json",
148+
"categories": ["code", "devops", "github"],
149+
"version": "1.0.0",
150+
"release_date": "2025-09-01T00:00:00Z",
151+
"latest": true
152+
},
153+
{
154+
"id": "local-linter",
155+
"name": "Local Linter",
156+
"description": "Runs lint checks against local files",
157+
"manifest_url": "file:///path/to/local/manifest.json",
158+
"categories": ["linting", "local", "devtools"],
159+
"version": "1.0.0",
160+
"release_date": "2025-09-01T00:00:00Z",
161+
"latest": true
162+
}
163+
],
164+
"total_count": 2,
165+
"updated_at": "2025-09-09T12:00:00Z"
166+
}
167+
```
168+
169+
Required fields:
170+
171+
* `id`: Unique identifier for the server
172+
* `name`: Display name for the server
173+
* `description`: Brief description of the server's functionality
174+
* `manifest_url`: URL pointing to the server's MCP manifest
175+
176+
Optional fields that provide additional metadata:
177+
178+
* `categories`: Array of category tags
179+
* `version`: Version identifier
180+
* `release_date`: ISO format release date
181+
* `latest`: Boolean indicating if this is the latest version
182+
* Additional fields like `total_count` and `updated_at` at the root level
183+
184+
### Azure API Center
185+
186+
For enterprises that want a dynamic and fully managed option, Azure API Center (part of Azure API Management) can be used as an MCP Registry. It provides governance features, discovery UI, and integration with existing API catalogs.
187+
188+
**Steps to set up with Azure API Center:**
189+
190+
1. Go to the Azure API Center portal.
191+
1. Create a new API Center instance (or reuse an existing one).
192+
1. Add your MCP servers as APIs, including their manifests and metadata.
193+
1. Publish your API Center instance.
194+
1. Copy the API Center endpoint URL—this becomes your MCP Registry URL.
195+
1. Paste this URL into the **MCP Registry URL (optional)** field in your {% data variables.product.prodname_enterprise %} or organization settings.
196+
197+
> [!NOTE]
198+
> Azure API Center includes a free tier for basic API cataloging and discovery. Larger organizations may choose to use paid Azure API Management plans for higher scale and advanced governance.
199+
200+
For more information, see [Azure API Center Documentation](https://docs.microsoft.com/en-us/azure/api-center/) and [Azure API Center Quickstart](https://docs.microsoft.com/en-us/azure/api-center/quickstart-create-api-center).

‎content/copilot/how-tos/administer-copilot/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ children:
1010
- /manage-for-organization
1111
- /manage-for-enterprise
1212
- /download-activity-report
13+
- /configure-mcp-server-access
1314
redirect_from:
1415
- /copilot/how-tos/administer
1516
contentType: how-tos

0 commit comments

Comments
 (0)