跳到主要内容

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 授予一个工具的访问权限。该指南通过允许和拒绝的 HTTP 检查单独验证网关路径。随后，连接 Cursor 或 VS Code，在真实 MCP 客户端中验证工具发现、所需批准和工具执行。两种管理路径配置的是同一个网关运行时和 MCP 端点。

客户端连接​

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

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

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

协议版本支持​

AISIX 网关通过 /mcp 和 /mcp/{server} 提供当前两代 MCP 协议，并自动与每个客户端协商，因此客户端无需进行 AISIX 专用配置：

MCP 协议修订版客户端支持情况说明
2026-07-28支持无状态修订版本：通过 server/discover 启动，无需握手，并在每个请求中携带协议元数据。
2025-11-25支持使用 initialize 握手。
2025-06-18支持使用 initialize 握手。
2025-03-26支持使用 initialize 握手。
2024-11-05不支持HTTP+SSE 传输代际；MCP 端点仅提供 Streamable HTTP。

协议涉及两种版本信号，网关会分别处理。对于 initialize 握手，网关会回显请求中受支持的 protocolVersion；如果请求的版本不受支持，则响应 2025-11-25。在握手之外的请求中，MCP-Protocol-Version HTTP 请求头是可选的：缺少该请求头时仍会接受请求，并按照规范的兼容规则将其视为 2025-03-26；如果请求头指定了不受支持的修订版，则返回 HTTP 400，并在 JSON-RPC 错误信封中列出受支持的修订版。采用 2026-07-28 生命周期的客户端可以从 server/discover 开始，无需握手。所有协议代际都以无状态方式提供服务：网关不会发出 Mcp-Session-Id，因此 MCP 请求在多个网关副本之间无需会话亲和性。

上游协议选择​

面向客户端的协议与上游会话相互独立：网关在 MCP 端点终止客户端协议，并为每个 type: mcp 的已注册服务器建立自己的会话。（openapi 工具源没有上游 MCP 会话，因此此设置不适用于该类型。）上游会话的修订版通过每个服务器的 protocol_version 设置选择：

protocol_version上游会话行为
未设置（默认）网关使用 initialize 握手建立会话，并协商一个受支持的 2025 Streamable HTTP 修订版本。对于仍会响应 initialize 的 2026-07-28 服务器，此方式同样有效。
"2026-07-28"网关通过无需握手的 server/discover 建立会话。对于不再响应 initialize 的服务器，必须使用此设置。

在 resources.yaml 中，省略 protocol_version 即可保留默认生命周期。在 AISIX Cloud 中，把 protocol_version 设置为 null 可移除现有固定设置；在更新时省略该字段则会保留固定设置。有关两种管理路径的配置步骤，请参阅固定 MCP 协议修订版。

版本选择是显式的：网关只使用已配置的生命周期，绝不会在不同协议代际之间探测或静默降级。当已配置的生命周期与服务器不兼容时，tools/list 会记录失败并从聚合列表中省略该服务器的工具，而对该服务器执行 tools/call 会返回上游失败。下游和上游的选择始终相互独立。

网关不会把调用方的 MCP-Protocol-Version 或 Mcp-Session-Id 请求头转发给上游服务器；只有当该服务器的 forward_client_headers 精确点名时，才会转发调用方的 Authorization。它使用服务器已注册的身份认证和协议设置建立独立的上游会话；有状态上游可以为该会话生成自己的会话标识符，而工具名称、参数和结果会按调用需要跨越该边界。

一致性

网关的持续集成会针对网关及桥接链提供的工具面运行官方 MCP 一致性测试套件中的适用场景，并将其作为阻止合并的检查。

治理 MCP 工具调用​

MCP 工具调用与模型请求共享相同的调用方 API Key 身份和遥测管道。它们与模型流量共享该 Key 的请求限制和并发限制；适用的安全护栏，以及 AISIX Cloud 中覆盖该调用方的预算也会生效。MCP 专用控制包括按服务器限流和工具授权：每把 Key 都可以携带自己的授权，AISIX Cloud 还可以叠加环境层和团队层。

使用以下指南进一步配置 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 自身的 mcp_access 配置块，以及在 AISIX Cloud 中环境和团队的 MCP 访问策略。
  • MCP 客户端把调用方 API Key 发送给 AISIX，而不是发送上游 MCP 凭证。

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

后续步骤​

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