跳到主要内容

MCP 网关概览

AISIX 网关通过聚合的 /mcp 端点代理已注册的模型上下文协议（MCP）工具源。工具源可以是使用 Streamable HTTP 的上游 MCP 服务器，也可以是通过 OpenAPI 文档描述的 REST API。有关 REST API 路径，请参阅把 REST API 公开为 MCP 工具。

MCP 客户端和 Agent 使用 AISIX 调用方 API Key 连接 /mcp，发现该 Key 可以使用的工具并调用它们，而不会获得上游 MCP 服务器的凭证。

这样，工具流量就与模型和 A2A 流量共享相同的身份认证、访问控制和遥测边界。一把调用方 API Key 可以同时治理调用方可使用的模型、可调用的 MCP 工具，以及可访问的 A2A Agent。

AISIX 对每个 MCP 请求执行身份认证，并根据调用方的有效工具授权过滤工具发现。对于 tools/call，AISIX 还会应用限流和安全护栏、检查适用的 AISIX Cloud 预算、使用已配置的上游凭证路由调用，并记录用量遥测。

MCP 网关的工作原理​

每个 MCP 服务器都有一个 name。在 AISIX Cloud 中，服务器注册在组织级别，并公开给选定环境。在开源 AISIX 网关中，服务器通常在 resources.yaml 中声明。AISIX 聚合已启用服务器的工具，并以带前缀的名称公开每个工具。

AISIX 使用两个下划线分隔已注册的服务器名称和上游工具名称。例如，github__create_issue 会路由到名为 github 的已注册 MCP 服务器，并调用其名为 create_issue 的上游工具。对于两种管理路径，服务器名称都不能包含保留分隔符 __，也不能以下划线结尾。名称内部可以使用单个下划线，例如 internal_tools。AISIX Cloud 还把名称限制为 56 个字母、数字、下划线、点或连字符，并要求首尾为字母或数字。

开始使用​

按照设置 MCP 网关中的步骤，通过 AISIX Cloud 或 resources.yaml 注册上游服务器，把一个工具授予调用方 API Key，并验证允许和拒绝的调用。两种管理路径配置的是同一个网关运行时和 MCP 端点。

客户端连接​

MCP 客户端通过 Streamable HTTP 连接 AISIX 代理监听器。使用 /mcp 访问聚合工具面：

设置值
服务器 URL<gateway-origin>/mcp
传输方式Streamable HTTP
请求头Authorization: Bearer <caller-api-key>

调用方 API Key 控制客户端可以发现和调用哪些工具。客户端只连接 AISIX，不会获得上游服务器 URL 或凭证。

治理 MCP 工具调用​

MCP 工具调用与模型请求共享相同的调用方 API Key 边界。无需为 MCP 流量配置单独的策略栈。

使用以下指南进一步配置 MCP 路径：

  • 控制工具访问：限制每把调用方 API Key 可以列出和调用的工具。
  • 限流和预算：应用调用方 API Key 请求和并发限制，并对 tools/call 请求使用 AISIX Cloud 预算。
  • 安全护栏：检查 MCP 工具参数和结果。
  • 可观测性：查看 MCP 工具调用发出的用量事件和指标。

AISIX Cloud 还提供共享的 MCP 访问策略以及服务器审查和批准工作流。

按服务器划分的端点​

当客户端要求每个已注册 MCP 服务器使用单独 URL 时，请使用 /mcp/{server}。该端点只呈现指定服务器。initialize 报告其注册名称，tools/list 通常以原始上游名称返回调用方有权使用的工具。tools/call 同时接受 create_issue 之类的原始名称和 github__create_issue 之类的聚合名称。

身份认证、工具访问、限流、安全护栏、用量遥测和 AISIX Cloud 预算的行为与 /mcp 相同。访问授权和按服务器限流在两种端点上都保留其 {server}__{tool} 身份，因此同时使用两种 URL 形式不会产生第二份限额。调用方身份认证通过后，未知或已禁用的服务器返回 404。

有关工具名称冲突行为和端点错误，请参阅代理 API 参考。如果现有客户端使用其他 URL 形式（例如 /mcp-servers/{server}/mcp），请通过 URL 重写将其映射到 /mcp/{server}。

排查工具访问问题​

如果客户端无法看到或调用某个工具，请检查以下项目：

  • MCP 服务器资源的 enabled 为 true。
  • 在 AISIX Cloud 中，服务器状态为 approved，且其 allowed_environments 包含调用方 API Key 所在的环境。
  • AISIX 网关可以访问上游 MCP 服务器，且已配置的上游身份认证有效。请参阅上游身份认证。
  • 调用方 API Key 的有效工具授权覆盖带前缀的工具名称。对于直接的按 Key 配置，请检查 allowed_tools；对于 AISIX Cloud 基于策略的访问，请检查适用的 MCP 访问策略和该 Key 的 mcp_access 设置。
  • MCP 客户端把调用方 API Key 发送给 AISIX，而不是发送上游 MCP 凭证。

有关 MCP 错误响应行为，请参阅请求头和错误码。有关端点级行为，请参阅代理 API 参考。

后续步骤​

使用以下指南配置 MCP 流量的处理方式：