Claude Code 深度学习手册

主题

托管 MCP 配置 ​

组织管理员限制用户可添加或连接哪些 MCP server。

是什么 ​

默认情况下，运行 Claude Code 的任何人都可以连接自己选择的任意 MCP server；Anthropic 仅按上架标准审核接入 Anthropic Directory 的 connector，但不对任何 MCP server 做安全审计或托管。作为管理员，你可以限制组织内允许运行哪些 server，控制范围从下发一组固定的已批准 server，到彻底禁用 MCP。

本页围绕两套机制展开：用 managed-mcp.json 下发固定 server 集合（独占控制），以及用 allowedMcpServers/deniedMcpServers 的允许名单/拒绝名单过滤用户所配置的 server。两者可单独或组合使用。

怎么工作 ​

  • managed-mcp.json 是独立文件，必须以管理员权限写入系统路径，无法通过 server-managed settings 下发，通常借助 Jamf、Group Policy、Intune 等设备管理工具部署。
  • 部署 managed-mcp.json 后 Claude Code 只加载该文件定义的 server，用户无法添加、修改或使用其他任何 MCP server（包括插件提供的 server）；默认还会抑制 claude.ai connector。
  • 其文件格式与项目级 .mcp.json 相同，使用 mcpServers 键，每个 server 含 type（http/sse/stdio）、url 或 command/args/env 等字段。
  • allowedMcpServers 与 deniedMcpServers 是过滤器而非注册表：server 必须先由用户、插件或 managed-mcp.json 添加，名单才会对其生效。
  • 加载每个 server 前按顺序执行三步检查：1) 合并所有来源的允许/拒绝名单；2) 检查拒绝名单，匹配即拦截且无法被覆盖；3) 检查允许名单，未设置则放行所有通过拒绝名单的 server。
  • 名单条目用三种键之一匹配：serverUrl（远程 URL，支持 * 通配符）、serverCommand（stdio 命令及全部参数须精确按序匹配）、serverName（用户自定义标签，仅精确匹配）。
  • 在 managed settings 中同时设置 allowedMcpServers 与 allowManagedMcpServersOnly: true，可让允许名单成为权威：用户/项目/本地设置中的允许名单被忽略；但拒绝名单始终从所有来源合并。

怎么配置 / 用法 ​

managed-mcp.json（独占控制）：

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

彻底禁用 MCP（空 server map）：

json
{ "mcpServers": {} }

硬性允许名单 + 拒绝名单：

json
{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

将允许名单限定为仅 managed 来源（managed settings 文件中）：

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

什么时候用 ​

  • 想给所有用户下发同一组固定 server 且不允许添加其他 server：用带目标 server 的 managed-mcp.json。
  • 想发布一份已批准 server 目录、用户自行添加其中的而拦截其余：allowedMcpServers + allowManagedMcpServersOnly: true。
  • 想强制一份允许名单但仍允许用户在自己的设置中放宽：只用 allowedMcpServers。
  • 只想拦截已知有问题的 server、其余全部放行：用 deniedMcpServers。
  • 想在组织内彻底禁用 MCP：部署含空 server map 的 managed-mcp.json。

限制 / 坑 ​

  • 任何机器用户都能读取 managed-mcp.json，因此不要在 env 中存放 API 密钥等凭据；应改用 ${VAR} 展开、OAuth/按用户 header 或 headersHelper。
  • 仅含 serverName 条目的允许名单不是安全控制：名称是用户自取的标签；要真正限定须用 serverCommand 或 serverUrl 条目。
  • 当某 server 被策略新拦截时，它会在 /mcp 和 claude mcp list 中静默消失、无任何提示原因，需主动告知受影响用户。
  • managed-mcp.json 无法通过 server-managed settings 下发，只能写入系统路径。
  • allowAllClaudeAiMcps 需要 Claude Code v2.1.149 或更高版本，且仅从管理员控制的策略层读取。

硬事实速查（12 条） ​

  • 三个系统路径：macOS /Library/Application Support/ClaudeCode/managed-mcp.json；Linux/WSL /etc/claude-code/managed-mcp.json；Windows C:\Program Files\ClaudeCode\managed-mcp.json。
  • 部署 managed-mcp.json 后 Claude Code 只加载其定义的 server，且默认抑制 claude.ai connector 与插件提供的 server。
  • allowedMcpServers 未设置=允许所有 server；设为空数组 []=不允许任何 server；已填充=仅允许匹配项。deniedMcpServers 未设置或为空都=不拦截。
  • 拒绝名单优先级最高：匹配任一拒绝条目即被拦截，无法被允许名单覆盖。
  • serverCommand 须精确匹配全部参数且按序。
  • serverUrl 支持任意位置的 * 通配符；主机名匹配不区分大小写并忽略末尾 FQDN 点，路径区分大小写。
  • allowManagedMcpServersOnly 为 true 时仅保留 managed 允许名单、忽略用户/项目/本地的允许名单，但拒绝名单始终从所有来源合并。
  • allowManagedMcpServersOnly 与 allowManagedPermissionRulesOnly 是两个独立设置。
  • 可用 strictPluginOnlyCustomization（list 中含 mcp）实现 server 只能来自插件。
  • 验证：claude mcp list 应只显示 managed-mcp.json 中的 server；尝试 add 会报 enterprise MCP configuration is active 错误。
  • 用户侧报错：被拒绝名单拦截显示 server is explicitly blocked by enterprise policy；不在允许名单显示 not allowed by enterprise policy。
  • 配置 OpenTelemetry 并设 OTEL_LOG_TOOL_DETAILS=1 后，可在工具事件中记录 MCP server 与工具名称用于监控。

官方出处：https://code.claude.com/docs/en/managed-mcp