{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此处获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 为你的组织控制 MCP 服务器访问

> 使用托管配置文件、允许列表和拒绝列表限制用户可以添加或连接的 MCP 服务器。

默认情况下，任何运行 Claude Code 的人都可以连接他们选择的任何 [MCP 服务器](/en/mcp)。Anthropic 在将连接器添加到 [Anthropic 目录](https://claude.ai/directory)之前会根据其[列表标准](https://claude.com/docs/connectors/building/review-criteria)进行审查，但不会安全审计或管理任何 MCP 服务器。作为管理员，你可以限制组织中运行的服务器，从部署固定的批准集合到完全禁用 MCP。

本页涵盖如何：

* [选择模式](#choose-a-pattern)以匹配你需要的控制程度
* [使用 `managed-mcp.json` 部署固定服务器集合](#exclusive-control-with-managed-mcp-json)，包括如何[完全禁用 MCP](#disable-mcp-entirely)
* [使用允许列表和拒绝列表控制服务器](#policy-based-control-with-allowlists-and-denylists)
* [告诉用户预期什么](#how-restrictions-appear-to-users)当限制阻止服务器时
* [监控组织实际使用的服务器](#monitor-mcp-usage)

<Note>
  [安全](/en/security)页面涵盖 MCP 威胁模型以及如何在批准之前评估服务器。[决定执行什么](/en/admin-setup#decide-what-to-enforce)将 MCP 限制与其他管理控制一起涵盖。
</Note>

## 选择模式

Claude Code 支持一系列限制级别。每个模式使用下面涵盖的一个或两个机制：`managed-mcp.json` 用于部署固定集合，`allowedMcpServers`/`deniedMcpServers` 用于过滤用户配置的内容。

| 模式                    | 作用                                                                                     | 配置                                                                                               |
| :---------------------- | :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| **禁用 MCP**            | 任何地方都不加载服务器                                                                   | `managed-mcp.json` 包含空服务器映射                                                                |
| **固定部署**            | 每个用户获得相同的服务器，无法添加其他                                                   | `managed-mcp.json` 包含你想要的服务器                                                              |
| **批准目录**            | 发布批准的服务器列表；用户添加他们想要的，其他都被阻止                                   | `allowedMcpServers` + `allowManagedMcpServersOnly: true`                                           |
| **仅插件服务器**        | 服务器只能来自插件；用户无法添加自己的                                                   | [`strictPluginOnlyCustomization`](/en/settings#strictpluginonlycustomization) 列表中包含 `mcp`     |
| **软允许列表**          | 执行允许列表，用户可以在自己的设置中扩大                                                 | `allowedMcpServers` 不带 `allowManagedMcpServersOnly`                                              |
| **仅拒绝列表**          | 阻止已知的不良服务器，允许其他所有                                                       | `deniedMcpServers`                                                                                 |
| **无限制**              | 用户添加任何内容                                                                         | 不部署任何托管 MCP 配置                                                                            |

<Note>
  Claude Code 没有内置的 MCP 服务器注册表供用户浏览和安装。对于批准目录模式，在用户可以找到的地方（如内部 wiki）共享批准的列表及其 `claude mcp add` 命令，或通过[托管插件市场](/en/plugin-marketplaces#managed-marketplace-restrictions)将服务器作为插件分发，以便用户可以从 `/plugin` 浏览和安装。
</Note>

## 使用 managed-mcp.json 进行独占控制

如果你部署 `managed-mcp.json` 文件，Claude Code 仅加载该文件定义的服务器。用户无法添加、修改或使用任何其他 MCP 服务器，包括插件提供的服务器。该文件还会抑制 claude.ai 连接器，除非你[在托管集合旁边允许它们](#allow-claude-ai-connectors-alongside-the-managed-set)。

另外两个设置可以进一步过滤托管集合：

* `allowedMcpServers` 和 `deniedMcpServers` 也适用于托管服务器，因此未通过它们的托管服务器不会加载。
* 用户自己的 `deniedMcpServers` 从他们的设置中合并，因此用户可以为自己阻止托管服务器。

参见[服务器如何被评估](#how-a-server-is-evaluated)了解完整的检查顺序。

`managed-mcp.json` 是独立文件，因此无法通过[服务器管理设置](/en/server-managed-settings)交付。任何可以以管理员权限写入系统路径的进程都可以部署它。大规模部署通常通过设备管理工具，如 macOS 上的 Jamf 或配置文件、Windows 上的组策略或 Intune，或 Linux 上你选择的车队管理。Claude Code 在以下路径之一查找该文件：

| 平台          | 路径                                                         |
| :------------ | :----------------------------------------------------------- |
| macOS         | `/Library/Application Support/ClaudeCode/managed-mcp.json`   |
| Linux 和 WSL  | `/etc/claude-code/managed-mcp.json`                          |
| Windows       | `C:\Program Files\ClaudeCode\managed-mcp.json`               |

该文件使用与项目 [`.mcp.json`](/en/mcp#project-scope) 文件相同的格式：

```json theme={null}
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.example.com"
      }
    }
  }
}
```

### 使用每用户凭据进行身份验证

机器上的任何用户都可以读取此文件，因此不要在 `env` 块中存储 API 密钥或其他凭据。改为使用以下方式传递每用户凭据：

* [`${VAR}` 扩展](/en/mcp#environment-variable-expansion-in-mcp-json)从每个用户的环境读取密钥。
* [OAuth 或每用户请求头](/en/mcp#authenticate-with-remote-mcp-servers)让每个用户以自己的身份进行身份验证。
* [`headersHelper`](/en/mcp#use-dynamic-headers-for-custom-authentication)在连接时生成凭据。

### 验证配置

要确认文件已生效，在托管机器上运行两项检查：

1. `claude mcp list` 仅显示 `managed-mcp.json` 中的服务器。如果用户自己的服务器仍然出现，则文件未被读取；检查路径和权限。
2. `claude mcp add --transport http test https://example.com/mcp` 失败并显示 `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`。URL 不需要是真实服务器，因为策略检查在联系任何内容之前就拒绝了命令。

### 完全禁用 MCP

部署包含空服务器映射的 `managed-mcp.json` 以阻止每个 MCP 服务器：

```json theme={null}
{
  "mcpServers": {}
}
```

用户在 `/mcp` 中看不到 MCP 服务器，`claude mcp add` 失败并显示上述企业策略错误。用户之前配置的服务器在下次启动会话时停止加载，没有警告说明策略是原因。

### 在托管集合旁边允许 claude.ai 连接器

部署 `managed-mcp.json` 默认会抑制 [claude.ai 连接器](/en/mcp#use-mcp-servers-from-claude-ai)，包括管理员在 claude.ai 管理控制台中为组织配置的连接器。要在 `managed-mcp.json` 中的服务器旁边加载这些连接器，在[托管设置源](/en/admin-setup#decide-how-settings-reach-devices)中设置 `"allowAllClaudeAiMcps": true`。需要 Claude Code v2.1.149 或更高版本。

启用该设置后，Claude Code 加载与未部署 `managed-mcp.json` 时相同的 claude.ai 连接器。[允许列表和拒绝列表](#policy-based-control-with-allowlists-and-denylists)仍然适用于这些连接器，因此你可以使用 `deniedMcpServers` 阻止特定连接器。该设置仅影响 claude.ai 连接器；插件提供的服务器保持抑制状态。

Claude Code 仅从管理员控制的策略层读取此设置：服务器管理设置、MDM 部署的 plist 或 HKLM 注册表项，或系统 `managed-settings.json` 文件。将其放在用户或项目设置中无效，因此用户无法重新启用独占控制抑制的连接器。

## 使用允许列表和拒绝列表进行策略控制

允许列表和拒绝列表过滤允许加载哪些已配置的服务器。它们不是注册表：服务器仍需由用户、插件或 `managed-mcp.json` 添加后，允许列表或拒绝列表才对其适用。要向用户部署服务器，使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json)。

要使允许列表具有权威性，在[托管设置源](/en/admin-setup#decide-how-settings-reach-devices)（如服务器管理设置或已部署的 `managed-settings.json` 文件）中同时设置 `allowedMcpServers` 和 `allowManagedMcpServersOnly: true`。[将允许列表限制为仅托管设置](#restrict-the-allowlist-to-managed-settings-only)显示配置。没有 `allowManagedMcpServersOnly` 时，来自每个设置源的允许列表会合并，包括用户自己的 `~/.claude/settings.json`，因此用户可以扩大你的允许列表允许的内容。拒绝列表始终从每个源合并。

<Note>
  `allowManagedMcpServersOnly` 与 `allowManagedPermissionRulesOnly` 分离，后者仅锁定[权限规则](/en/permissions#managed-settings)。设置该标志不会强制执行 MCP 允许列表。
</Note>

### 按 URL、命令或名称匹配服务器

`allowedMcpServers` 和 `deniedMcpServers` 是条目列表。每个条目是一个具有单个键的对象，通过 URL、命令或名称标识服务器：

| 键              | 匹配方式                                              | 用途                                 |
| :-------------- | :---------------------------------------------------- | :----------------------------------- |
| `serverUrl`     | 远程服务器 URL，精确匹配或带 `*` 通配符               | HTTP 和 SSE 服务器                   |
| `serverCommand` | 启动 stdio 服务器的确切命令和参数                     | Stdio 服务器                         |
| `serverName`    | 用户分配的标签。仅精确匹配；不展开通配符              | 两种类型，但请参阅下方警告           |

将 `allowedMcpServers` 保持未设置与设置为空数组不同：

| 设置                | 未设置（默认）      | 空数组 `[]`     | 有内容                        |
| :------------------ | :------------------ | :-------------- | :---------------------------- |
| `allowedMcpServers` | 允许所有服务器      | 不允许任何服务器 | 仅允许匹配的服务器            |
| `deniedMcpServers`  | 不阻止任何服务器    | 不阻止任何服务器 | 阻止匹配的服务器              |

<Warning>
  仅使用 `serverName` 条目的允许列表不是安全控制。名称是用户在运行 `claude mcp add` 或编辑配置文件时分配的标签，不是底层服务器，因此用户可以将任何服务器命名为 `github`。要强制执行实际运行的服务器，添加 `serverCommand` 或 `serverUrl` 条目。
</Warning>

### 服务器如何被评估

在加载服务器之前（包括来自 `managed-mcp.json` 的服务器），Claude Code 按顺序运行三项检查：

1. **合并列表。** 来自每个设置源的允许列表和拒绝列表条目合并为一个允许列表和一个拒绝列表。当 `allowManagedMcpServersOnly` 为 `true` 时，仅保留托管允许列表；拒绝列表始终从每个源合并。
2. **检查拒绝列表。** 匹配任何拒绝列表条目（按 URL、命令或名称）的服务器被阻止。任何内容都无法覆盖拒绝列表匹配。
3. **检查允许列表。** 如果任何地方都没有设置 `allowedMcpServers`，通过拒绝列表的每个服务器都会加载。如果设置了，服务器必须匹配的内容取决于其类型，如下表所示。

| 服务器类型               | 允许条件                                                                                       |
| :----------------------- | :--------------------------------------------------------------------------------------------- |
| 远程（HTTP 或 SSE）      | 匹配 `serverUrl` 条目。仅当允许列表不包含 `serverUrl` 条目时，`serverName` 匹配才算数           |
| Stdio                    | 匹配 `serverCommand` 条目。仅当允许列表不包含 `serverCommand` 条目时，`serverName` 匹配才算数   |

在这些检查中有两条匹配规则：

* **命令精确匹配。** 每个参数，按顺序。`["npx", "-y", "server"]` 不匹配 `["npx", "server"]` 或 `["npx", "-y", "server", "--flag"]`。
* **URL 支持 `*` 通配符**，可在模式中的任何位置，包括协议。主机名匹配不区分大小写并忽略尾随的 FQDN 点，因此 `https://Mcp.Example.com/*` 匹配 `https://mcp.example.com/api`。路径保持区分大小写。

| 模式                        | 允许                                                     |
| :-------------------------- | :------------------------------------------------------- |
| `https://mcp.example.com/*` | 特定域上的所有路径                                       |
| `https://mcp.example.com`   | 同样是该域上的所有路径。没有路径的模式匹配任何路径       |
| `https://*.example.com/*`   | `example.com` 的任何子域                                 |
| `http://localhost:*/*`      | localhost 上的任何端口                                    |
| `*://mcp.example.com/*`     | 到特定域的任何协议                                       |

### 示例配置

以下配置设置了带拒绝列表的硬允许列表。高亮行更改了列表其余部分的评估方式，块后的标注解释了每一行：

```json {3,5,11} theme={null}
{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}
```

* **第 3 行**：第一个 `serverUrl` 条目。一旦存在，每个远程服务器必须匹配 URL 模式，因此用户无法通过给未列出的远程服务器一个允许的名称来通过。
* **第 5 行**：第一个 `serverCommand` 条目。对 stdio 服务器有相同效果，因此每个本地服务器必须精确匹配列出的命令。
* **第 11 行**：拒绝列表中的 `serverName` 条目。拒绝列表条目始终适用，因此任何名为 `dangerous-server` 的服务器无论其 URL 或命令如何都会被阻止。

此允许列表中的 `serverName` 条目永远不会匹配任何内容，因为两种传输类型已经有更严格的条目。

下面的手风琴展示了服务器如何针对其他允许列表和拒绝列表组合进行评估。

<Accordion title="仅 URL 允许列表">
  ```json theme={null}
  {
    "allowedMcpServers": [
      { "serverUrl": "https://mcp.example.com/*" },
      { "serverUrl": "https://*.internal.example.com/*" }
    ]
  }
  ```

  | 服务器                                                    | 结果                                       |
  | :-------------------------------------------------------- | :----------------------------------------- |
  | `https://mcp.example.com/api` 上的 HTTP 服务器            | 允许：匹配 URL 模式                        |
  | `https://api.internal.example.com/mcp` 上的 HTTP 服务器   | 允许：匹配通配符子域                       |
  | `https://external.example.com/mcp` 上的 HTTP 服务器       | 阻止：不匹配任何 URL 模式                  |
  | 任何命令的 Stdio 服务器                                   | 阻止：没有名称或命令条目可匹配             |
</Accordion>

<Accordion title="仅命令允许列表">
  ```json theme={null}
  {
    "allowedMcpServers": [
      { "serverCommand": ["npx", "-y", "approved-package"] }
    ]
  }
  ```

  | 服务器                                                    | 结果                             |
  | :-------------------------------------------------------- | :------------------------------- |
  | 使用 `["npx", "-y", "approved-package"]` 的 Stdio 服务器  | 允许：匹配命令                   |
  | 使用 `["node", "server.js"]` 的 Stdio 服务器              | 阻止：不匹配命令                 |
  | 名为 `my-api` 的 HTTP 服务器                              | 阻止：没有名称条目可匹配         |
</Accordion>

<Accordion title="混合名称和命令允许列表">
  ```json theme={null}
  {
    "allowedMcpServers": [
      { "serverName": "github" },
      { "serverCommand": ["npx", "-y", "approved-package"] }
    ]
  }
  ```

  | 服务器                                                                   | 结果                                                               |
  | :----------------------------------------------------------------------- | :----------------------------------------------------------------- |
  | 名为 `local-tool` 使用 `["npx", "-y", "approved-package"]` 的 Stdio 服务器 | 允许：匹配命令                                                     |
  | 名为 `local-tool` 使用 `["node", "server.js"]` 的 Stdio 服务器           | 阻止：命令条目存在但不匹配                                         |
  | 名为 `github` 使用 `["node", "server.js"]` 的 Stdio 服务器               | 阻止：当命令条目存在时 stdio 服务器必须匹配命令                    |
  | 名为 `github` 的 HTTP 服务器                                             | 允许：匹配名称                                                     |
  | 名为 `other-api` 的 HTTP 服务器                                          | 阻止：名称不匹配                                                   |
</Accordion>

<Accordion title="仅名称允许列表">
  ```json theme={null}
  {
    "allowedMcpServers": [
      { "serverName": "github" },
      { "serverName": "internal-tool" }
    ]
  }
  ```

  | 服务器                                              | 结果                            |
  | :-------------------------------------------------- | :------------------------------ |
  | 名为 `github` 使用任何命令的 Stdio 服务器           | 允许：无命令限制                |
  | 名为 `internal-tool` 使用任何命令的 Stdio 服务器    | 允许：无命令限制                |
  | 名为 `github` 的 HTTP 服务器                        | 允许：匹配名称                  |
  | 任何名为 `other` 的服务器                           | 阻止：名称不匹配                |
</Accordion>

<Accordion title="带拒绝列表覆盖的允许列表">
  ```json theme={null}
  {
    "allowedMcpServers": [
      { "serverUrl": "https://*.example.com/*" }
    ],
    "deniedMcpServers": [
      { "serverUrl": "https://staging.example.com/*" }
    ]
  }
  ```

  | 服务器                                           | 结果                                                     |
  | :----------------------------------------------- | :------------------------------------------------------- |
  | `https://mcp.example.com/api` 上的 HTTP 服务器   | 允许：匹配允许列表 URL 模式，无拒绝列表匹配              |
  | `https://staging.example.com/api` 上的 HTTP 服务器 | 阻止：两者都匹配，但拒绝列表优先                        |
  | `https://other.com/mcp` 上的 HTTP 服务器         | 阻止：不匹配允许列表                                     |
</Accordion>

### 将允许列表限制为仅托管设置

要使托管允许列表成为唯一适用的，在托管设置文件中设置 `allowManagedMcpServersOnly`：

```json theme={null}
{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}
```

当 `allowManagedMcpServersOnly` 为 `true` 时，来自用户、项目和本地设置的允许列表被忽略。拒绝列表仍然从所有源合并，因此用户始终可以为自己阻止服务器。

## 限制对用户的表现形式

当限制阻止服务器时，用户会看到 `claude mcp add` 的错误或服务器静默停止加载。使用此表识别这些报告，并在推出更改之前告诉用户预期什么：

| 限制                                                               | 用户看到的内容                                                                                       |
| :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| 存在 `managed-mcp.json` 且用户运行 `claude mcp add`               | `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers` |
| 服务器在拒绝列表上且用户运行 `claude mcp add`                      | `Cannot add MCP server "<name>": server is explicitly blocked by enterprise policy`                  |
| 服务器不在允许列表上且用户运行 `claude mcp add`                    | `Cannot add MCP server "<name>": not allowed by enterprise policy`                                   |
| 之前配置的服务器现在被策略阻止                                     | 服务器从 `/mcp` 和 `claude mcp list` 中静默消失，无警告                                              |

在最后一种情况下，用户没有信号表明策略是服务器消失的原因，因此在推出新限制时告诉受影响的用户哪些服务器被阻止。

## 监控 MCP 使用情况

当配置了 [OpenTelemetry 导出](/en/monitoring-usage)时，Claude Code 可以记录用户调用哪些 MCP 服务器和工具。设置 `OTEL_LOG_TOOL_DETAILS=1` 以在工具事件中包含 MCP 服务器和工具名称，然后在收集器中聚合它们以查看用户实际连接了哪些服务器。参见[监控](/en/monitoring-usage)了解设置导出器和完整事件模式。

## 配置摘要

本页涵盖的每个文件和设置，它们控制什么，以及如何交付：

| 载体                         | 控制内容                                                                | 存放位置                                                                                                                       | 如何交付                                                                                                                                                                |
| :--------------------------- | :---------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `managed-mcp.json`           | 固定服务器集合，独占控制                                                | 系统路径：`/Library/Application Support/ClaudeCode/`、`/etc/claude-code/` 或 `C:\Program Files\ClaudeCode\`                  | MDM、GPO、车队管理或任何具有管理员权限的进程。无法通过服务器管理设置设置                                                                                                |
| `allowedMcpServers`          | 允许的服务器的允许列表                                                  | 任何[设置文件](/en/settings#settings-files)；除非设置了 `allowManagedMcpServersOnly`，否则来自每个源的条目会合并              | 对于执行，[托管设置源](/en/admin-setup#decide-how-settings-reach-devices)：服务器管理设置、`managed-settings.json`、MDM 配置文件或注册表                                  |
| `deniedMcpServers`           | 被阻止服务器的拒绝列表                                                  | 任何设置文件；来自每个源的条目会合并                                                                                         | 与 `allowedMcpServers` 相同                                                                                                                                             |
| `allowManagedMcpServersOnly` | 将允许列表锁定为仅托管源                                                | 仅托管设置源；该设置在其他地方无效                                                                                           | 与 `allowedMcpServers` 相同                                                                                                                                             |
| `allowAllClaudeAiMcps`       | 在 `managed-mcp.json` 旁边加载 claude.ai 连接器而不是抑制它们           | 仅托管设置源；该设置在其他地方无效                                                                                           | 与 `allowedMcpServers` 相同                                                                                                                                             |

## 相关资源

* [决定执行什么](/en/admin-setup#decide-what-to-enforce)：MCP 限制与权限规则、沙盒和其他管理控制
* [通过 MCP 将 Claude Code 连接到工具](/en/mcp)：完整的 MCP 参考，包括传输、范围和身份验证
* [设置](/en/settings)：设置层次结构和托管设置如何优先
* [服务器管理设置](/en/server-managed-settings)：从 Claude.ai 管理控制台交付 `allowedMcpServers` 和 `deniedMcpServers`
* [安全](/en/security)：这些控制防御的威胁模型
* [Claude 企业管理员指南](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、席位管理和推出手册