控制组织的 MCP 服务器访问权限

• 选择一个模式，该模式与您需要的控制程度相匹配
• 使用 managed-mcp.json 部署固定服务器集，包括如何完全禁用 MCP
• 通过托管设置提供服务器，同时用户保留他们自己的服务器
• 使用允许列表和拒绝列表控制服务器
• 告诉用户当限制阻止服务器时会发生什么
• 监控您的组织实际使用的服务器

​

选择一个模式

​

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

• 该文件定义的服务器
• 你通过 managedMcpServers 提供的服务器
• 启动会话的应用程序注册的进程内服务器，例如 VS Code 扩展自己的服务器或桌面应用程序提供的连接器
• 内置的Chrome 中的 Claude 服务器，如果你允许它与托管集合一起使用

​

部署 managed-mcp.json

{
  "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"
      }
    }
  }
}

​

使用按用户凭证进行身份验证

• ${VAR} 扩展从每个用户的环境中读取机密。
• OAuth 或按用户标头使每个用户以自己的身份进行身份验证。
• headersHelper在连接时生成凭证。

​

通过 --mcp-config 或 --strict-mcp-config 传递的服务器

• 在工作站上，Claude Code 在启动时退出，显示 You cannot dynamically configure MCP servers when an enterprise MCP config is present。
• 在云会话中，在部署了该文件的主机上，例如自托管运行器，Claude Code 仅使用托管服务器启动，并跳过 claude.ai 连接器和云主机通过 --mcp-config 交付的其他服务器。会话中没有任何内容告诉用户哪些服务器被遗漏了。Claude Code 在其 stderr 上以警告的形式命名它们，自托管运行器在 debug 日志级别记录这些警告。

​

允许列表和拒绝列表如何应用于托管集合

• deniedMcpServers 也适用于托管服务器，因此与条目匹配的托管服务器将不会加载。
• 用户自己的 deniedMcpServers 从他们的设置中合并，因此用户可以为自己阻止托管服务器。

​

验证配置

1. claude mcp list 仅显示 managed-mcp.json 中的服务器，加上你通过 managedMcpServers 提供的任何服务器。另外两个结果意味着出现了问题：
   • 如果用户自己的服务器仍然出现，Claude Code 没有读取该文件，因此请检查其路径和父目录的权限。
   • 如果文件的服务器没有出现，且 MCP config diagnostics 部分将企业配置标记为解析失败，Claude Code 无法读取或解析该文件。修复该部分命名的错误，然后让用户重新启动 Claude Code。
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

{
  "mcpServers": {}
}

​

允许 claude.ai 连接器与托管集合一起使用

​

允许 Chrome 中的 Claude 与托管集合一起使用

​

通过托管设置提供服务器

{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    },
    "records": {
      "type": "http",
      "url": "https://records.example.com/mcp",
      "headers": {
        "X-Records-Key": "key-issued-for-all-claude-code-users"
      }
    }
  }
}

​

条目可以包含的内容

• type 是 http 或 sse。与 .mcp.json 中一样，streamable-http 被接受为 http 的别名。
• url 是 https:// URL。Claude Code 拒绝纯 http:// URL，包括指向 localhost 的 URL。
• 该条目没有 command、args、env 或 headersHelper 成员，因此托管设置文档永远不会命名要在用户机器上运行的程序。
• 没有值包含 ${VAR} 引用。Claude Code 不会在这些条目中展开环境变量，因此请写入字面值。
• 服务器名称仅包含字母、数字、连字符和下划线，没有键或值包含控制或不可见的格式字符。

​

提供的服务器如何加载

• 提供的服务器优先于本地、项目或用户范围内同名的服务器，以及指向相同 URL 的插件服务器或 claude.ai 连接器。
• 如果您还部署 managed-mcp.json，Claude Code 会加载其服务器和提供的服务器，当两者都定义一个名称时，该文件的条目优先。
• 当 strictPluginOnlyCustomization 锁定 mcp 表面时，提供的服务器继续加载。
• deniedMcpServers 适用于提供的服务器，包括来自用户自己设置的条目，因此用户可以为自己阻止一个。提供的服务器不需要 allowedMcpServers 条目。

• 用户使用同一名称下的 --mcp-config 传递的服务器替换该运行的提供的服务器，并针对 allowedMcpServers 进行检查。
• --strict-mcp-config 将提供的服务器与所有其他配置的服务器一起排除。

​

用户可以看到和更改的内容

• claude mcp remove 报告服务器由组织提供。
• 当您还没有部署 managed-mcp.json 时，用户在同一名称下添加的条目会被保存但在您的条目存在时不会被使用。
• 用户仍然可以在 /mcp 中为自己关闭提供的服务器，该服务器在托管 MCPs 下列出提供的服务器。

​

managedMcpServers 适用的位置

​

提供的服务器何时连接

• 在具有缓存设置的机器上，Claude Code 会保留此密钥的缓存副本，直到服务器确认会话的设置，并等待该确认后再加载 MCP 服务器。如果确认失败，会话将继续而不使用提供的服务器，/status 会说它们被保留。
• 在机器的首次启动时，还没有缓存任何内容，在设置到达之前启动的交互式会话会在它们到达时立即连接提供的服务器，而已经启动的 claude -p 运行可以在没有它们的情况下完成。

• 添加服务器：Claude Code 在更新的设置到达时连接它，无需重启。
• 更改服务器的条目：这些会话使用新定义重新连接到它。
• 删除服务器：运行中的交互式会话在读取更改的设置后断开连接。非交互式（-p）运行会保留它直到结束。

​

使用允许列表和拒绝列表进行基于策略的控制

​

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

​

serverName 条目如何匹配

• 在 deniedMcpServers 中，serverName 接受任何非空字符串，因此您可以按显示名称阻止 claude.ai 连接器。例如，{ "serverName": "claude.ai Slack" } 阻止 Slack 连接器。当您需要拒绝对重命名具有鲁棒性时，或当连接器名称冲突并获得 (N) 后缀时，更倾向于使用 serverUrl 条目。
• 在 allowedMcpServers 中，serverName 仅限于字母、数字、连字符和下划线。使用 serverUrl 将 Claude Code 自身获取的 claude.ai 连接器列入允许列表；对于云主机提供给自托管会话的连接器，请改用连接器流量离开您的网络下列出的条目。

​

serverCommand 条目如何匹配

• 命令精确匹配。 每个参数，按顺序。["npx", "-y", "server"] 不匹配 ["npx", "server"] 或 ["npx", "-y", "server", "--flag"]。
• 不比较 env 块。 ["node", "server.js"] 匹配以任何 env 值运行该命令的服务器。某些环境变量会改变 node 在启动时加载的内容。要自行设置 env 值，请在 managed-mcp.json 中定义该服务器。

​

serverUrl 条目如何匹配

• 完整写出的主机名：仅默认端口，https 为 443，http 为 80
• 包含 * 的主机名：所有端口

• https://staging.example.com/*：仅阻止该主机上端口 443 的 https 服务器，因此不会阻止位于 https://staging.example.com:8443/api 的服务器
• https://staging.example.com:*/*：阻止该主机上所有端口的 https 服务器
• *://staging.example.com:*/*：阻止该主机的任何方案和任何端口

​

serverCommand 和 serverUrl 条目中的环境变量

• 服务器的配置值：从实时进程环境展开，就像 .mcp.json 的其余部分一样
• 策略条目：从固定环境展开，因此由项目或用户设置文件设置的变量无法更改允许列表条目的含义

​

服务器如何被评估

1. 合并列表。 来自每个设置作用域的允许列表和拒绝列表条目合并为一个允许列表和一个拒绝列表。当 allowManagedMcpServersOnly 为 true 时，仅保留托管允许列表；拒绝列表始终从每个作用域合并。当存在多个托管源时，从每个管理员源读取的键说明其中哪些提供托管作用域的列表。
2. 检查拒绝列表。 与任何拒绝列表条目匹配的服务器（按 URL、命令或名称）被阻止。没有任何东西可以覆盖拒绝列表匹配。
3. 检查允许列表。 某些服务器跳过此检查。如果 allowedMcpServers 未在任何地方设置，每个通过拒绝列表的服务器都会加载。如果已设置，服务器必须匹配的内容取决于其类型，如下表所示。

​

跳过允许列表检查的服务器

• 组织自己的服务器：每个 managedMcpServers 条目，以及任何其值不使用 ${VAR} 展开的 managed-mcp.json 条目。
• 内置服务器，例如 Chrome 中的 Claude、Claude Code 在运行的 VS Code 或 JetBrains IDE 中连接的 ide 服务器，以及 CLI 本身配置的服务器。
• Claude Tag 会话的 Slack 工具：它用来读取线程和发布回复的服务器无需允许列表条目即可加载。

​

示例配置

{
  "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 或命令如何。

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

{
  "allowedMcpServers": [
    { "serverUrl": "https://*.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://staging.example.com/*" }
  ]
}

​

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

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