跳到主要内容

控制 MCP 工具访问

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

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

工具访问如何工作​

工具访问权限保存在调用方 API Key 的 allowed_tools 字段中，其值是一组带前缀的工具名或匹配模式。字段省略、为 null 或为空列表时，该 Key 没有任何 MCP 工具访问权限。

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

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

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

请为调用方选择满足需求的最小权限：精确名称提供最窄授权；当调用方可以使用某个服务器的所有工具时使用按服务器通配；只有允许访问当前和未来所有 MCP 工具的 Key 才使用 *。

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

创建带工具权限的 Key​

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

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__*", "runbooks__search"]
  }'

❶ 当该 Key 仅用于 MCP 流量时，请使用空的模型允许列表。

❷ 该授权允许调用 github 服务器上的全部工具，外加单个 runbooks__search 工具，不允许调用其它工具。

更新 Key 的工具访问权限​

当工具授权发生变化时，请更新调用方 API Key。Admin API 的 PUT 会替换整个 Key 资源，因此请同时带上现有 Key 哈希和其它需要保留的字段，以及新的 allowed_tools：

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__create_issue"]
  }'

这次更新会让该 Key 继续保持仅用于 MCP，并把之前的工具授权替换为仅允许 github__create_issue。如果该 Key 同时需要模型访问权限，请在更新中保留原有 allowed_models 值。

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

执行方式​

当 MCP 客户端列出工具时，AISIX 会汇总每个已启用服务器的工具，然后把列表过滤为调用方 API Key 允许的工具。客户端只会看到被允许的工具。

当客户端调用工具时，AISIX 会在联系上游服务器之前再次根据 allowed_tools 检查该 Key。该 Key 不允许的工具会以中性 MCP 错误被拒绝，且不会路由到上游。该拒绝不会透露该工具或服务器是否存在。

托管控制面​

在托管部署中，请通过控制面配置工具访问权限，而不是直接发送这些 Admin API 命令。相同的授权模型仍然适用：调用方 API Key 可以限定到单个工具、某个服务器上的全部工具，或该环境中可用的全部 MCP 工具。该工作流适用于 AISIX Cloud 和 AISIX Cloud On-Premises。

下一步​

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

  • 限流与预算：把请求限制、并发限制和预算应用到 MCP 工具调用。
  • 安全护栏：检查 MCP 工具参数和工具结果。
  • 调用方 API Key：了解同样治理模型和 A2A 流量的共享 Key 设置。