控制 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。

工具访问的工作原理

对于直接的按 Key 配置，工具访问存储在调用方 API Key 的 allowed_tools 字段中。其值是一组带前缀的工具名称或模式。字段省略、设为 null 或设为空列表时，该 Key 没有任何 MCP 工具访问权限。AISIX Cloud 也可以从共享 MCP 访问策略派生授权，详见权限执行的工作原理。

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

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

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

精确名称提供最窄访问权限。当调用方可以使用某个服务器的所有工具时，使用按服务器通配符；只有允许某把 Key 访问当前和未来所有 MCP 工具时才使用 *。

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

需要管理大量 Key？

按 Key 白名单提供最细粒度的控制。在 AISIX Cloud 中，使用通过策略管理 MCP 访问可在环境或团队级别授予访问权限。调用方 API Key 随后可以继承共享授权；如果 all 或匹配的通配符覆盖到后来注册的工具，这些工具也会被继承。

配置工具访问

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

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": [],
    "allowed_tools": ["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 工具，不允许调用其他工具。

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

更新工具访问

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

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 '{
    "allowed_tools": ["github__create_issue"]
  }'

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

要撤销该 Key 的全部 MCP 工具访问权限，请把 allowed_tools 设置为 []。该 Key 会保留模型访问权限和其他配置，但不能再列出或调用任何 MCP 工具。

开源 AISIX 网关

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

resources.yaml
api_keys:
  - display_name: mcp-caller
    key_env: MCP_CALLER_KEY
    allowed_models: []
    allowed_tools:
      - github__*
      - runbooks__search

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

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

权限执行的工作原理

当 MCP 客户端列出工具时，AISIX 会聚合每个已启用服务器的工具，然后按照调用方的有效授权过滤列表。直接按 Key 配置使用 allowed_tools。在 AISIX Cloud 中，配置了 mcp_access 的 Key 会根据适用的 MCP 访问策略和 Key 的 mcp_access 模式派生授权。客户端只会看到允许访问的工具。

当客户端调用工具时，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 控制面​

后续步骤​