使用策略管理 MCP 访问权限

当调用方数量较少时，在每个调用方 API Key 上单独授权 MCP 工具很方便。规模扩大后，每次注册新的 MCP 服务器或工具都可能需要更新数百个 Key。MCP 访问策略把授权中共享的部分提升到环境或团队层级，使其对这些层覆盖的所有 Key 生效。

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

各层如何组合

一个调用方 API Key 最多受三层约束。它们都只有 allow 和 deny 两个字段，且任何一层都不会覆盖其他层：

环境策略：作用于环境内的每个 Key。
团队策略：作用于绑定到某个团队的 Key，在组织的所有环境中生效。
Key 的 mcp_access 配置块：Key 自身的那一层。

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

有效权限 =（所有存在的层的 allow 取交集）−（所有存在的层的 deny 取并集）

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

allow 取交集。 只有当所有存在的层都允许某个工具时，它才可用；因此任何一层都只能收窄结果，都不能扩大结果。团队策略无法授予环境策略未开放的工具，Key 同样不能。
deny 始终优先。 任何一层中的拒绝模式都会移除对应工具，无论其他层如何允许。
缺失的层不施加约束，但一层都没有则不授予任何权限。 没有 mcp_access 配置块的 Key、没有策略的团队、以及被禁用的策略，都只是退出交集运算。当三者都未配置时，该 Key 没有任何 MCP 工具访问权限——权限总是被显式授予，绝不会因为缺少配置而产生。

由于每一层都必须给出 allow，两种边界情况总是被显式写出，而不是靠省略字段隐含：

`allow`	含义
`[]`	该层不允许任何工具，因此它覆盖的每个 Key 都会失去 MCP 访问权限。
`["*"]`	该层不收窄任何范围。用于只通过 `deny` 做扣除的层。

所有模式都使用控制工具访问权限中描述的 <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 '{
    "allow": ["github__*"],
    "deny": ["github__delete_repository"]
  }'

❶ 该环境只允许 github 下的所有工具。只有在所有当前和未来服务器上的所有工具都应可达时，才发送 ["*"]；发送 [] 则会关闭整个环境的 MCP 访问权限。

❷ 拒绝模式适用于环境中的每个 Key，无论团队层和 Key 层如何配置。

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

为 Key 配置自己的层

没有配置自己那一层的 Key，会取得环境层和团队层留下的全部权限：

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": []
  }')

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

当 Key 应当比环境层和团队层更受限时，为它添加 mcp_access 配置块：

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

该配置块就是这个 Key 完整的允许范围，因此 "allow": [] 会让它完全没有 MCP 访问权限，而 "allow": ["*"] 则不收窄任何范围——适用于只想通过自身 deny 做扣除的 Key。更新时发送 "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": {
      "layers": [
        {
          "source": "env_policy",
          "policy_id": "a5065729-3049-407a-90d4-357a6ab214c2"
        }
      ],
      "all_tools": false,
      "allow": [
        {
          "pattern": "github__*",
          "source": "env_policy"
        }
      ],
      "deny": [
        {
          "pattern": "github__delete_repository",
          "source": "env_policy"
        }
      ]
    }
  }
}

layers 为空数组表示任何一层都没有配置，这正是此类 Key 没有 MCP 工具访问权限的原因。控制台在 API Keys 页面的 Key 行中提供相同的视图。

授予团队策略

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

请从团队页面复制 Team ID，然后为请求导出该值：

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": { "allow": ["postgres__*"] }
  }'

团队层与环境层取交集，而不是替换它：只有在环境策略同样允许时，成员 Key 才能访问 postgres__*。发送 "mcp": null 可移除该层，之后成员 Key 只受环境层约束。

运维说明

策略可以设置 "enabled": false。被禁用的策略根本不构成一层：它既不授权也不拒绝，直接退出交集运算。
删除环境策略后，既没有团队策略也没有 mcp_access 配置块的 Key 将不再受任何层约束，因而没有 MCP 访问权限。解析过程遵循故障关闭原则，绝不会故障开放。
未经授权的工具会从 tools/list 中过滤，并在发生任何上游路由前拒绝 tools/call，同时返回相同的中性错误。
每次策略写入和权益变更都会记录在审计日志中。

后续步骤

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

各层如何组合​

前置条件​

设置环境策略​

为 Key 配置自己的层​

验证有效访问权限​

授予团队策略​

运维说明​

后续步骤​