Skip to content

Commit ad3b2a0

Browse files
docs-botdocs-bot
authored
Merge pull request #40973 from github/repo-sync
Repo sync
2 parents 58f0de9 + 445a741 commit ad3b2a0

File tree

2 files changed

+163
-77
lines changed

2 files changed

+163
-77
lines changed

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

Lines changed: 160 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
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 %}.
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 %}.
44
permissions: Enterprise owners and organization owners
55
product: '{% data variables.copilot.copilot_enterprise_short %} or {% data variables.copilot.copilot_business_short %}'
66
versions:
@@ -14,51 +14,79 @@ contentType: how-tos
1414
---
1515

1616
> [!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.
17+
> The MCP registry URL and allowlist are in {% data variables.release-phases.public_preview %} and subject to change.
1918
2019
## Overview
2120

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.
21+
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 server exposes.
2322

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:
23+
As an enterprise or organization owner, you can configure an **MCP registry URL**, allowing you to:
2724
* **Provide a curated catalog** of MCP servers your developers can discover and use
28-
* **Restrict access** to unapproved servers for more granular access control
25+
* **Restrict access** to unapproved servers for increased security and compliance
2926
* **Give clarity to developers** when a server is blocked by policy
3027

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.
28+
If you haven't created an MCP registry yet, see [Setting up an MCP registry](#setting-up-an-mcp-registry) later in this article.
3229

3330
## About MCP policy settings
3431

3532
The following settings let you control how MCP servers are discovered and accessed in your organization or enterprise.
3633

37-
### MCP servers policy
34+
### MCP servers in {% data variables.product.prodname_copilot_short %}
3835

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
36+
First, you must set the overall **MCP servers in {% data variables.product.prodname_copilot_short %}** policy:
37+
* Enabled for all: MCP servers are allowed (default behavior depends on registry configuration)
38+
* Disabled for all: No MCP servers can be used by any users with {% data variables.product.prodname_copilot_short %} seats from this enterprise or organization
39+
* Let organizations decide (Enterprise only): Child organizations can set their own MCP policies
4340

4441
### MCP Registry URL
4542

46-
The **MCP Registry URL** is an optional field where you specify the endpoint of your discoverable or restricted internal MCP registry.
43+
The **MCP Registry URL** is an optional field where you specify the URL of your discoverable or restricted internal MCP registry. When you configure a registry URL:
4744

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
45+
* The servers listed in the registry are displayed in supported IDEs
46+
* The "Restrict MCP access to registry servers" setting becomes configurable
5147

52-
### "Restrict MCP access to registry servers" setting
48+
### Restrict MCP access to registry servers
5349

5450
Under the **Restrict MCP access to registry servers** setting, you choose how strictly to enforce registry-based access:
5551

5652
* **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"`.
53+
* **Registry only**: Developers can only run MCP servers that are explicitly listed in the uploaded MCP registry. In IDE UIs, blocked servers appear greyed out with a warning message. In the `mcp.json` configuration file, they may also show `"run": "blocked"`.
54+
55+
> [!NOTE]
56+
> If you choose the "Registry only" option with the MCP registry URL cleared, all MCP servers will be blocked.
57+
58+
#### Current enforcement limitations
59+
60+
The "Registry only" setting currently has the following limitations:
61+
62+
* Enforcement is based only on server name/ID matching, which can be bypassed by editing configuration files
63+
* Strict enforcement that prevents installation of non-registry servers is not yet available
64+
65+
For the highest level of security, you can **disable MCP servers in {% data variables.product.prodname_copilot_short %}** until strict enforcement is available.
5866

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.
67+
## How MCP policies apply to your users
68+
69+
MCP policies apply to **all users who receive {% data variables.product.prodname_copilot_short %} seats** from the organization or enterprise where the policy is configured.
70+
71+
When a policy is enabled or disabled at the enterprise level, it is automatically applied to all child organizations and their members, and cannot be overridden by those organizations.
72+
73+
When an enterprise lets child organizations configure their own MCP policies, each organization must choose its own registry URL and enforcement settings. This allows teams with different security or compliance needs to choose the configuration that works best for them.
74+
75+
## Support for MCP policies
76+
77+
| Surface | Registry display | Allowlist enforcement |
78+
|---|:---:|:---:|
79+
| {% data variables.copilot.copilot_cli_short %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
80+
| {% data variables.copilot.copilot_coding_agent %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
81+
| Eclipse | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
82+
| JetBrains | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
83+
| {% data variables.product.prodname_vs %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
84+
| {% data variables.product.prodname_vscode_shortname %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} |
85+
| {% data variables.product.prodname_vscode_shortname %} Insiders | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
86+
| Xcode | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
87+
88+
> [!NOTE]
89+
> For Eclipse, JetBrains, and Xcode, these features are supported in the pre-release versions of {% data variables.product.prodname_copilot_short %}.
6290
6391
## Configuring the MCP allowlist policy for an enterprise
6492

@@ -73,10 +101,7 @@ Under the **Restrict MCP access to registry servers** setting, you choose how st
73101
* **Allow all**: No restrictions. All MCP servers can be used.
74102
* **Registry only**: Only servers from the registry may run.
75103

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.
104+
Your chosen policy will immediately apply to developers in your enterprise.
80105

81106
## Configuring the MCP allowlist policy for an organization
82107

@@ -90,10 +115,7 @@ Your chosen policy will immediately apply to developers in your enterprise.
90115
* **Allow all**: No restrictions. All MCP servers can be used.
91116
* **Registry only**: Only servers from the registry may run.
92117

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.
118+
Your chosen policy will immediately apply to developers in your organization.
97119

98120
## How are MCP allowlists enforced?
99121

@@ -117,84 +139,145 @@ The resolution logic is:
117139

118140
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.
119141
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).
142+
1. **Recency of registry upload**: If two policies have the same scope and strictness, the most recently uploaded registry wins.
143+
1. **Tie-breaker**: If all else is equal, the lowest internal ID wins.
122144

123145
> [!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.
146+
> 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 is used.
125147
>
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.
148+
> **For uniform access**, you can set and maintain your MCP registry URL and allowlist policy at the enterprise level.
149+
>
150+
> **For varied team needs**, configure separate policies for each organization, ensuring users only belong to one organization to avoid policy conflicts.
151+
152+
## Setting up an MCP registry
153+
154+
If you don't already have an MCP registry configured, there are a few different ways you can create one depending on your needs.
155+
156+
### Self-hosting a registry
157+
158+
At its core, a registry is a set of HTTPS endpoints that serve details about the included MCP servers. To make your registry reachable, you can take any of the following paths:
159+
* Fork and self-host the open-source MCP Registry
160+
* Run the open-source registry locally using Docker
161+
* Publish your own custom implementation
127162

128-
## Setting up an MCP Registry
163+
To get started with the open-source registry, see the [MCP Registry Quickstart](https://github.com/modelcontextprotocol/registry/tree/main?tab=readme-ov-file#quick-start) in the `github/modelcontextprotocol` repository.
129164

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.
165+
A valid registry must:
166+
* Be reachable over HTTPS
167+
* Support URL routing
131168

132-
### Simple/static registry
169+
To successfully configure your registry, you need to implement the following endpoints:
133170

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.
171+
* `GET /v0.1/servers`: Returns a list of all included MCP servers
172+
* `GET /v0.1/servers/{serverName}/versions/latest`: Returns the latest version of a specific server
173+
* `GET /v0.1/servers/{serverName}/versions/{version}`: Returns the details for a specific version of a server
135174

136-
### Example registry format
175+
#### Example registry format
137176

138-
Your registry must return a JSON response with the following structure:
177+
Your registry must return a JSON response following [the v0.1 MCP registry specification](https://registry.modelcontextprotocol.io/docs#/operations/list-servers-v0.1):
139178

140-
``` json
179+
```json
141180
{
142181
"servers": [
143182
{
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
183+
"_meta": {
184+
"io.modelcontextprotocol.registry/official": {
185+
"status": "active",
186+
"publishedAt": "2025-09-01T00:00:00Z",
187+
"isLatest": true
188+
}
189+
},
190+
"server": {
191+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
192+
"name": "io.github.modelcontextprotocol/server-github",
193+
"description": "Official GitHub MCP server for repository management, issues, and pull requests.",
194+
"version": "1.0.0",
195+
"packages": [
196+
{
197+
"registryType": "npm",
198+
"identifier": "@modelcontextprotocol/server-github",
199+
"version": "1.0.0",
200+
"transport": { "type": "stdio" }
201+
}
202+
],
203+
"remotes": [
204+
{
205+
"type": "http",
206+
"url": "https://api.githubcopilot.com/mcp/"
207+
}
208+
]
209+
}
152210
},
153211
{
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
212+
"_meta": {
213+
"io.modelcontextprotocol.registry/official": {
214+
"status": "active",
215+
"publishedAt": "2025-09-01T00:00:00Z",
216+
"isLatest": true
217+
}
218+
},
219+
"server": {
220+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
221+
"name": "io.github.modelcontextprotocol/server-filesystem",
222+
"description": "MCP server for secure file system operations with configurable access controls.",
223+
"version": "1.0.0",
224+
"packages": [
225+
{
226+
"registryType": "npm",
227+
"identifier": "@modelcontextprotocol/server-filesystem",
228+
"version": "1.0.0",
229+
"transport": { "type": "stdio" }
230+
}
231+
]
232+
}
162233
}
163234
],
164-
"total_count": 2,
165-
"updated_at": "2025-09-09T12:00:00Z"
235+
"metadata": {
236+
"count": 2,
237+
"nextCursor": null
238+
}
166239
}
167240
```
168241

169242
Required fields:
170243

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
244+
* `server.name`: Reverse DNS identifier for the MCP server
245+
* `server.description`: Brief summary of server functionality
246+
* `server.version`: Version string
247+
* `server.packages`: Required if the server provides a local installation (`registryType`, `identifier`, `version`, `transport`)
248+
* `server.remotes`: Required if the server provides hosted endpoints (`type`, `url`)
175249

176250
Optional fields that provide additional metadata:
177251

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
252+
* `_meta`: Registry-managed metadata (`status`, `publishedAt`, `isLatest`)
253+
* `metadata`: Pagination details (`count`, `nextCursor`)
254+
* Additional publisher-provided fields may appear under `server._meta`
183255

184-
### Azure API Center
256+
#### Support for v0.1
185257

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.
258+
To avoid breaking changes to your registry in the future, you should implement v0.1 of the MCP registry specification. Be aware that v0.1 is currently only supported in {% data variables.product.prodname_vscode_shortname %} Insiders, with other surfaces adding support soon. See the following table for more details.
187259

188-
**Steps to set up with Azure API Center:**
260+
| Surface | v0.1 support date |
261+
| ---------------------- | ----------------- |
262+
| {% data variables.product.prodname_vscode_shortname %} Insiders | Oct 23, 2025 |
263+
| {% data variables.product.prodname_vs %} | Nov 5, 2025 |
264+
| {% data variables.product.prodname_vscode_shortname %} | Nov 14, 2025 |
265+
| Eclipse | Dec 2025 |
266+
| JetBrains IDEs | Dec 2025 |
267+
| Xcode | Dec 2025 |
268+
269+
### Using Azure API Center as a registry
270+
271+
> [!NOTE]
272+
> Azure API Center requires an Azure API Management subscription to function as an MCP registry. For pricing details, see [MCP management availability](https://learn.microsoft.com/en-us/azure/api-management/mcp-server-overview#availability) and [API Management pricing](https://azure.microsoft.com/en-us/pricing/details/api-management/) in the Azure API Center documentation.
273+
274+
For enterprises that want a dynamic and fully managed option, Azure API Center can be used as an MCP registry. It provides governance features, discovery UI, and integration with existing API catalogs.
189275

190276
1. Go to the Azure API Center portal.
191277
1. Create a new API Center instance (or reuse an existing one).
192278
1. Add your MCP servers as APIs, including their manifests and metadata.
193279
1. Publish your API Center instance.
194-
1. Copy the API Center endpoint URL—this becomes your MCP Registry URL.
280+
1. Copy the API Center endpoint URL—this becomes your MCP registry URL.
195281
1. Paste this URL into the **MCP Registry URL (optional)** field in your {% data variables.product.prodname_enterprise %} or organization settings.
196282

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://learn.microsoft.com/en-us/azure/api-center/) and [Azure API Center Quickstart](https://learn.microsoft.com/en-us/azure/api-center/set-up-api-center).
283+
For more information, see [Register and discover remote MCP servers in your API inventory](https://learn.microsoft.com/en-us/azure/api-center/register-discover-mcp-server) in the Azure API Center Documentation.

‎content/copilot/tutorials/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ redirect_from:
3232
contentType: tutorials
3333
heroImage: /assets/images/banner-images/hero-3.png
3434
layout: bespoke-landing
35+
sidebarLink:
36+
text: All tutorials
37+
href: /copilot/tutorials
3538
recommended:
3639
- /copilot/tutorials/copilot-chat-cookbook
3740
- /copilot/tutorials/customization-library

0 commit comments

Comments
 (0)