使用策略管理 MCP 访问权限

当调用方数量较少时，为每个 Key 配置 allowed_tools 授权很方便。规模扩大后，每次注册新的 MCP 服务器或工具都可能需要更新数百个 API Key。MCP 访问策略把共享授权提升到环境或团队层级，使每个 Key 可以继承、收窄或拒绝该授权。

本指南介绍各策略层如何组合、如何配置环境和团队授权、如何迁移现有 Key，以及如何查看 Key 的有效访问权限。

策略组合方式

策略包含三个层级，范围从大到小：

环境默认策略：环境内 Key 的基础授权。
团队权益：团队级授权，它会在组织的每个环境中替换该团队 Key 的环境默认策略。
Key 的 mcp_access 配置块：决定单个 Key 如何参与策略，可以继承授权、收窄授权或退出授权。

每次请求都会解析 Key 的有效访问权限：

基础授权 = 如果 Key 所属团队具有权益，则使用团队权益；否则使用环境默认策略
有效权限 =（基础授权 ∩ Key 限制）− 所有适用的拒绝模式

以下两条规则让该模型保持可预测：

Key 只能收窄继承的授权，不能扩大授权。 restrict 模式的 Key 会将自己的模式与基础授权取交集；基础授权之外的模式不会增加任何权限。
拒绝始终优先。 环境策略、团队权益和 Key 中的拒绝模式都会被扣除。即使团队权益替换了环境授权，环境级拒绝仍然有效；它也适用于仍使用显式 allowed_tools 列表的 Key。

没有 mcp_access 配置块的 Key 会保留原有的单 Key 白名单行为：其 allowed_tools 列表就是完整的允许范围，策略绝不会扩大该范围，只会叠加策略中的拒绝模式。升级不会静默授予访问权限。

所有模式都使用与 allowed_tools 相同的 <server>__<tool> 命名方式和单个 * 通配符匹配规则。

前置条件

本页示例使用 AISIX Cloud Admin API。请准备组织的控制面 URL、环境 ID 和具有写入权限的 Admin Token，并安装 curl 和 jq。

对于 On-Premises 部署，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。然后设置：

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

设置环境默认策略

保存环境默认策略：

curl -sS -X PUT "$AISIX_CP/environments/$ENV_ID/mcp_policy" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "selected",
    "allow": ["github__*"],
    "deny": ["github__delete_repository"]
  }'

❶ selected 只授权与 allow 匹配的工具。使用 none 表示不授权任何工具。只有在所有当前和未来服务器上的所有工具都应可用时，才使用 all。

❷ 拒绝模式适用于环境中的每个 Key，包括仍使用显式 allowed_tools 列表的 Key。

控制台在 Environment → MCP Access 中提供相同的编辑器。

选择 Key 的参与方式

Key 的 mcp_access 配置块决定它如何与策略组合：

API_KEY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "inheriting-caller",
    "allowed_models": [],
    "mcp_access": {
      "mode": "inherit"
    }
  }')

export API_KEY_ID=$(echo "$API_KEY_RESPONSE" | jq -r '.api_key.id')
echo "$API_KEY_RESPONSE" | jq

❶ inherit 会原样使用继承的授权。使用 restrict 可将 Key 自己的 allow 模式与继承授权取交集，并扣除自身的 deny 模式。使用 deny 则不授予任何 MCP 工具访问权限。

以下 restrict Key 会在更广泛的授权中只访问一个服务器：

"mcp_access": {
  "mode": "restrict",
  "allow": ["github__*"],
  "deny": ["github__delete_repository"]
}

完全省略 mcp_access，可让 Key 继续使用显式 allowed_tools 白名单。更新时发送 "mcp_access": null，可让策略管理的 Key 恢复到该行为。

验证有效访问权限

查看新 Key，确认每个允许或拒绝模式由哪项策略提供：

curl -sS "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID/effective_permissions" \
  -H "Authorization: Bearer $AISIX_TOKEN" | jq

该 Key 会继承上面配置的环境策略：

{
  "effective_permissions": {
    "mcp": {
      "key_mode": "inherit",
      "base_source": "env_policy",
      "all_tools": false,
      "allow": [
        {
          "pattern": "github__*",
          "source": "env_policy"
        }
      ],
      "deny": [
        {
          "pattern": "github__delete_repository",
          "source": "env_policy"
        }
      ]
    }
  }
}

key_mode: legacy 表示 Key 仍由显式 allowed_tools 管理。控制台的 API Keys 页面也会在 Key 所在行显示相同视图。

授予团队权益

团队权益按团队配置一次，并应用到该团队在组织所有环境中的调用方 API Key。如果团队通过身份服务提供方组同步（参见 SCIM 目录同步），组成员变更会自动传播，无需逐个修改 Key。

export TEAM_ID="YOUR_TEAM_ID"

curl -sS -X PUT "$AISIX_CP/teams/$TEAM_ID/entitlements" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp": { "mode": "selected", "allow": ["postgres__*"] }
  }'

团队权益会替换成员 Key 的环境默认策略，而不会与之合并。发送 "mcp": null 可移除该权益，之后成员 Key 会回退到各环境的默认策略。

迁移现有 Key

现有 Key 在切换为 inherit 前会保留显式 allowed_tools 行为，策略不会隐式扩大其权限。迁移是一次带预览的批量操作。

先预览影响。响应会统计受影响的 Key，并列出各 Key 的模式变化（最多 50 个样本，发生变化的 Key 优先）：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/mcp_policy/preview" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "preview": {
    "total_keys": 214,
    "legacy_keys": 209,
    "policy_managed_keys": 5,
    "keys_gaining": 187,
    "keys_losing": 12,
    "keys_unchanged": 10,
    "samples": [
      { "id": "…", "display_name": "ci-bot", "mode": "legacy", "gained": ["github__*"], "lost": [] }
    ]
  }
}

可以在请求体中发送候选策略（{"policy": {…}}），在保存前评估其影响。比较基于模式：它报告授权的模式，不会将模式展开为具体工具名。

然后切换这些 Key：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/mcp_policy/apply" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

响应会报告已切换的 Key 数量：

{
  "updated": 209
}

所有仍使用显式白名单的 Key 都会切换为 mcp_access: {"mode": "inherit"}；发送 key_ids 可以只切换部分 Key。每个 Key 之前的 allowed_tools 值会保留，因此可以清除单个 Key 的 mcp_access 来恢复原行为。迁移完成后，注册新的 MCP 服务器或工具无需再修改 Key。

运维说明

策略可以设置 "enabled": false；禁用的策略既不授权也不拒绝，Key 会回退到下一个适用层级。
当 Key 处于 inherit 模式时删除环境默认策略，会使不属于任何已授权团队的 Key 失去 MCP 访问权限。解析过程遵循故障关闭原则，绝不会故障开放。
执行方式与单 Key 白名单一致：未经授权的工具会从 tools/list 中过滤，并在发生任何上游路由前拒绝 tools/call，同时返回相同的中性错误。
每次策略写入、权益变更和批量迁移都会记录在审计日志中。

后续步骤

验证策略后，请参见 MCP 网关概览注册并连接 MCP 服务器。然后为工具调用路径添加限流和预算、安全护栏或可观测性。

策略组合方式​

前置条件​

设置环境默认策略​

选择 Key 的参与方式​

验证有效访问权限​

授予团队权益​

迁移现有 Key​

运维说明​

后续步骤​