控制 MCP 工具访问

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

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

前置条件

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

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

工具访问的工作原理

工具访问存储在调用方 API Key 的 mcp_access 字段中，它是一个包含 allow 列表和可选 deny 列表的对象。该配置块是这把 Key 在工具 ACL 中自己的那一层：在 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 Cloud 中，使用通过策略管理 MCP 访问可在环境或团队级别授予访问权限。没有配置自己那一层的 Key 会跟随共享层，包括后来注册、被匹配通配符覆盖到的工具。

配置工具访问

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

AISIX Cloud

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

创建 Key

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

export AISIX_CP="http://localhost:8080/api"
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 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 Cloud 控制面

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

后续步骤

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

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

前置条件​

工具访问的工作原理​

配置工具访问​

AISIX Cloud​

创建 Key​

更新工具访问​

开源 AISIX 网关​

权限执行的工作原理​

AISIX Cloud 控制面​

后续步骤​