控制 MCP 工具访问

对于 MCP 流量，调用方 API Key 是工具访问边界。只有显式授予访问权限后，某把 Key 才能列出或调用 MCP 工具。

当不同客户端需要通过同一个网关访问不同上游工具时，请配置工具访问。本指南说明 AISIX 如何命名聚合工具、如何创建或更新带工具访问权限的 Key，以及调用方列出或调用工具时如何执行权限检查。

前置条件

开始前，请准备以下环境：

• 对于 AISIX Enterprise 或 AISIX Cloud，准备一个环境、已注册的 MCP 服务器和写入作用域管理员 Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 入门操作。若要申请 AISIX Cloud 访问权限，请联系 API7。
• 对于开源 AISIX 网关，在 resources.yaml 中准备一把调用方 API Key 和已注册的 MCP 服务器。设置 MCP 网关提供了可运行的配置以及验证和重新加载工作流。
• 控制面示例需要 cURL 和 jq。

工具访问的工作原理

工具访问存储在调用方 API Key 的 mcp_access 字段中，它是一个包含 allow 列表和可选 deny 列表的对象。该配置块是这把 Key 在工具 ACL 中自己的那一层：在 AISIX Enterprise 和 AISIX Cloud 中，它会与环境和团队的 MCP 访问策略取交集，因此 Key 只能收窄这些层允许的范围，不能扩大。

省略该配置块时，这把 Key 不施加自己的约束，也就是取得各策略层留下的全部权限——而当任何一层都没有配置时，它没有任何 MCP 工具访问权限。权限总是被显式授予。

AISIX 采用 <server>__<tool> 形式命名每个公开的工具。<server> 是已注册 MCP 服务器的 name，<tool> 是上游工具名称。例如，github__create_issue 会调用已注册 github 服务器上的上游 create_issue 工具。

每个 allow 条目都会与带前缀的工具名称匹配：

条目	授权范围	示例
精确名称	一个指定工具。	github__create_issue 只允许该工具。
<server>__*	一个已注册服务器上的全部工具。	github__* 允许 github__create_issue、github__list_repos 以及任何其他 github 工具。
*	所有已注册服务器上的全部工具。	* 允许当前和未来的所有工具。

精确名称提供最窄访问权限。当调用方可以使用某个服务器的所有工具时，使用按服务器通配符；只有当这把 Key 不需要收窄任何范围时才使用 *——它通常与 deny 搭配，用于只做扣除的场景。allow 为空列表则表示该 Key 完全没有 MCP 访问权限。

条目是单星号 glob，因此通配符可以出现在末尾按服务器形式之外。例如，*__search 会授权每个已注册服务器上名为 search 的工具。除非确实需要跨服务器模式，否则应优先使用按服务器或精确授权。

deny 使用相同的模式，且始终优先：被它匹配到的工具不可用，无论这把 Key 或任何策略层如何允许。

需要管理大量 Key？

Key 自身的配置块提供最细粒度的控制。在 AISIX Enterprise 和 AISIX Cloud 中，使用通过策略管理 MCP 访问可在环境或团队级别授予访问权限。没有配置自己那一层的 Key 会跟随共享层，包括后来注册、被匹配通配符覆盖到的工具。

配置工具访问

请通过与你的部署对应的管理路径配置工具访问。

AISIX Enterprise 或 AISIX Cloud

使用 Admin API 创建带工具访问权限的调用方 API Key，或更新现有 Key 的工具授权。

创建 Key

导出控制面 URL、管理员 Token 和环境 ID：

# AISIX_CP 包含 /api，末尾不带斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

创建 MCP 客户端使用的调用方 API Key。下面示例授权一个服务器上的所有工具，以及另一个服务器上的单个工具：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "mcp-caller",
    "allowed_models": [],
    "mcp_access": { "allow": ["github__*", "runbooks__search"] }
  }' > api_key.json

export API_KEY_ID=$(jq -r '.api_key.id' api_key.json)
export CALLER_KEY=$(jq -r '.plaintext' api_key.json)

❶ 当该 Key 仅用于 MCP 流量时，使用空的模型白名单。

❷ 该层允许调用 github 服务器上的全部工具，外加单个 runbooks__search 工具，不允许调用其他工具。在 AISIX Enterprise 和 AISIX Cloud 中，这把 Key 实际可达的范围还要受环境层和团队层的限制。

响应会在 plaintext 中返回且只返回一次明文 Bearer Key。请立即将其安全存储在客户端；后续读取只返回 Key 元数据。MCP 客户端在网关请求中以 Authorization: Bearer <plaintext> 发送该值。

更新工具访问

当工具授权发生变化时，请更新调用方 API Key。更新是部分更新：只有发送的字段会发生变化，而 mcp_access 会作为一个完整配置块被替换：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_access": { "allow": ["github__create_issue"] }
  }'

这次更新会把之前的配置块替换为仅允许 github__create_issue。由于请求没有包含模型访问权限和其他设置，这些配置保持不变。

要撤销该 Key 的全部 MCP 工具访问权限，请发送 "mcp_access": {"allow": []}。该 Key 会保留模型访问权限和其他配置，但无论各策略层如何允许，它都不能再列出或调用任何 MCP 工具。发送 "mcp_access": null 的含义则不同：它会移除这把 Key 自己的层，使它重新跟随环境层和团队层。

开源 AISIX 网关

在 resources.yaml 的调用方条目上设置 mcp_access：

resources.yaml（MCP 访问权限）

api_keys:
  - display_name: mcp-caller
    key_env: MCP_CALLER_KEY
    allowed_models: []
    mcp_access:
      allow:
        - github__*
        - runbooks__search

在网关进程环境中设置 MCP_CALLER_KEY。该调用方可以使用 github 下注册的每个工具，以及 runbooks 下注册的 search 工具。包括模型和 A2A 访问在内的其他调用方设置仍位于同一条目上。

资源文件没有策略层，因此 Key 自己的配置块就是唯一的一层——没有 mcp_access 的调用方条目因而无法访问任何 MCP 工具。

若要更改授权，请编辑完整配置块、验证 resources.yaml 并重新加载网关。设置 allow: [] 可以撤销所有 MCP 工具访问，同时保留该 Key 的其他权限。有关验证和重新加载命令，请参阅设置 MCP 网关。

权限执行的工作原理

当 MCP 客户端列出工具时，AISIX 会聚合每个已启用服务器的工具，然后按照调用方的有效授权过滤列表——也就是适用于这把 Key 的所有层的交集。客户端只会看到允许访问的工具。

当客户端调用工具时，AISIX 会在联系上游服务器之前再次检查有效授权。调用方无权访问的工具会以中性 MCP 错误被拒绝，且不会路由到上游。该拒绝不会透露该工具或服务器是否存在。

同一授权也适用于按服务器划分的端点。AISIX 以带命名空间的 <server>__<tool> 形式评估每个工具，然后通常以原始名称呈现允许访问的工具。例如，对 github__create_issue 的授权会在 /mcp/github 上呈现 create_issue，但不会授权访问其他服务器端点上的任何工具。

AISIX Enterprise 或 AISIX Cloud

你也可以通过控制面用户界面配置工具访问权限，而不是使用上面的 API 调用。相同的授权模型仍然适用：调用方 API Key 可以限定到单个工具、某个服务器上的全部工具，或该环境中可用的全部 MCP 工具。该工作流同时适用于 AISIX Enterprise 和 AISIX Cloud。

后续步骤

你现在已限定每把调用方 API Key 可以列出和调用的 MCP 工具。使用以下指南添加运行时控制，或查看共享的调用方 Key 设置：

• 限流和预算：应用请求和并发限制，并为 MCP 工具调用配置控制面预算。
• 安全护栏：检查 MCP 工具参数和结果。
• 调用方 API Key：查看同样治理模型和 A2A 流量的共享 Key 设置。