MCP 网关概览

AISIX AI 网关可以通过一个网关端点前置已注册的上游 Model Context Protocol（MCP）服务器。一个 MCP 服务器是一个注册项，对应一个通过 Streamable HTTP 提供 MCP 能力的上游服务器。

MCP 客户端和 Agent 使用 AISIX 调用方 API Key 连接 /mcp，发现该 Key 可以使用的工具，并在不拿到上游 MCP 服务器凭证的情况下调用这些工具。

这让工具流量与模型流量和 A2A 流量使用同一个认证、访问控制、策略和遥测边界。一个调用方 API Key 可以同时控制允许使用的模型、允许调用的 MCP 工具，以及允许访问的 A2A Agent。

AISIX 会认证调用方、检查工具访问权限，并应用限流、预算和安全护栏。随后，它会使用你配置的凭证把调用路由到已注册的上游 MCP 服务器，并记录 MCP 用量遥测。

下面的示例会注册一个服务器、授予工具访问权限，并让 MCP 客户端通过自托管网关连接。

MCP 网关如何工作

每个上游 MCP 服务器都会以 display_name 注册为一个网关资源。AISIX 会聚合已启用服务器的工具，并用带前缀的名称暴露每个工具。

AISIX 使用两个下划线分隔注册的服务器名称和上游工具名称。例如，github__create_issue 会路由到名为 github 的 MCP 服务器，并调用其上游工具 create_issue。注册名称不能包含 __，因为 AISIX 会保留该分隔符用于 MCP 工具路由；常规字段名仍然可以使用单下划线。

MCP 客户端连接 AISIX 代理监听器上的 /mcp。上游 MCP 服务器必须使用 Streamable HTTP transport。

注册并连接 MCP 服务器

下面的示例会注册一个上游 MCP 服务器，授予调用方 API Key 访问该服务器工具的权限，并让 MCP 客户端通过网关连接。

准备工作

下面示例使用自托管 AISIX 网关。运行前请准备以下内容：

一个 Admin 和代理监听器都可用的 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个网关可访问的 Streamable HTTP 上游 MCP 服务器。
一个 MCP 客户端将发送给 AISIX 的调用方 API Key。

对于托管部署，请使用控制面，而不是下面的自托管 Admin API 命令。你可以从 MCP servers 页面注册 MCP 服务器、暴露到目标环境，并在同一控制面中配置工具访问权限、限流、预算和安全护栏。概念相同，只是管理界面不同。该工作流适用于 AISIX Cloud 和 AISIX Cloud On-Premises。

注册上游 MCP 服务器

下面示例注册一个使用 Bearer Token 认证的上游 MCP 服务器。请为上游端点创建服务器资源：

# Replace with your values
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export MCP_UPSTREAM_TOKEN="YOUR_UPSTREAM_MCP_TOKEN"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "github",
    "url": "https://mcp.example.com/mcp",
    "auth_type": "bearer",
    "secret": "'"${MCP_UPSTREAM_TOKEN}"'",
    "timeout_ms": 5000
  }'

❶ display_name 会成为该服务器工具的命名空间前缀，例如 github__create_issue。它必须唯一，且不能包含 __。

❷ url 是 AISIX 通过 Streamable HTTP 访问的上游 MCP 端点。

❸ auth_type: "bearer" 表示 AISIX 使用 Bearer Token 认证上游。其它凭证模式请参见上游认证。

❹ secret 会把上游凭证保存在网关侧。AISIX 会用它访问上游，且不会向调用方返回该值。

❺ timeout_ms 会限制每个上游操作，包括连接、列出工具和调用工具。

你应该会看到类似下面的响应：

{
  "id": "6f64f080-17d7-44d9-b995-6a353e71f6bc",
  "value": {
    "display_name": "github",
    "url": "https://mcp.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "timeout_ms": 5000,
    "enabled": true
  },
  "revision": 1
}

如果后续需要更新、查看或删除该服务器，请保存返回的 id。

上游凭证选项请参见上游认证。

完整请求和响应 schema 请参见 Admin API 参考中的创建 MCP 服务器操作。

授予工具访问权限

调用方使用 AISIX 调用方 API Key 连接 /mcp，不是 Admin Key。访问权限需要显式授予：没有 allowed_tools 的 Key 不能列出或调用任何 MCP 工具。

创建允许访问目标工具的调用方 API Key。创建资源前，请先对明文调用方 Key 计算哈希：

# Replace with your values
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="sk-demo-caller"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

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__*"]
  }'

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

❷ ["github__*"] 会授权访问 github 服务器上的全部工具。只授权单个工具时，请填写完整的前缀工具名；授权全部 MCP 工具时使用 ["*"]。匹配规则请参见控制 MCP 工具访问。

如果后续需要更新该调用方 API Key，请保存返回的 id。

连接 MCP 客户端

把 MCP 客户端或 agent 配置为通过 Streamable HTTP 连接 AISIX 代理端点 /mcp，并在 Authorization 请求头中发送调用方 API Key。

如果你的 MCP 客户端接受 JSON 配置，请把这些值映射到该客户端特定的 schema 中。具体字段名因客户端而异：

{
  "mcpServers": {
    "aisix": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "Streamable HTTP",
      "headers": {
        "Authorization": "Bearer sk-demo-caller"
      }
    }
  }
}

连接后，从客户端列出工具。工具列表只会包含调用方 API Key 允许访问的工具。在本例中，工具调用会使用 github__ 前缀，例如 github__create_issue。

治理 MCP 工具调用

MCP 工具调用与模型请求共用同一个调用方 API Key 边界，因此不需要为 MCP 流量单独配置一套策略。

使用下面的指南细化 MCP 路径：

控制 MCP 工具访问：把每个调用方 API Key 限定到它可以列出和调用的工具。
限流与预算：把调用方 API Key 的请求限制、并发限制和预算应用到 tools/call 请求。
安全护栏：检查 MCP 工具参数和工具结果。
可观测性：查看 MCP 工具调用产生的用量事件和指标。

排查工具访问问题

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

MCP 服务器资源已 enabled。
上游 MCP 服务器可以从 AISIX 网关访问，且配置的上游认证有效。参见上游认证。
调用方 API Key 的 allowed_tools 覆盖该带前缀的工具名（精确名称、<server>__* 授权或 *）。
MCP 客户端发送给 AISIX 的是调用方 API Key，而不是上游 MCP 凭证。

MCP 错误响应行为请参见响应头与错误码。端点级行为请参见代理 API 参考。

下一步

你已经了解如何注册 MCP 服务器、授予调用方访问权限，并让 MCP 客户端通过 AISIX 连接。使用下面的指南继续细化 MCP 流量治理：

上游认证：配置 AISIX 如何认证到每个上游服务器。
控制 MCP 工具访问：将调用方限定到特定工具、整个服务器或全部工具。
限流与预算：把调用方 API Key 的请求限制、并发限制和预算应用到工具调用。
安全护栏：检查 MCP 工具参数和工具结果。
可观测性：查看 MCP 工具调用产生的用量事件和指标。

MCP 网关如何工作​

注册并连接 MCP 服务器​

准备工作​

注册上游 MCP 服务器​

授予工具访问权限​

连接 MCP 客户端​

治理 MCP 工具调用​

排查工具访问问题​

下一步​