MCP Gateway

AISIX 可以通过单一 MCP 端点暴露已注册的上游 MCP Server。Agent 连接到 AISIX 后，可以发现调用方 API Key 被允许访问的工具，并在不获取上游 MCP Server 凭证的情况下调用这些工具。

这让 Agent 工具流量与模型流量共用同一层认证、策略和遥测边界。AISIX 会认证调用方、检查工具访问权限、将调用路由到已注册的上游 MCP Server，并记录 MCP 工具调用遥测。

MCP Gateway 如何工作

每个上游 MCP Server 都会注册为一个 Admin API 资源。AISIX 会根据该服务器的显示名称为其工具添加前缀并对外暴露。

AISIX 使用两个下划线分隔已注册的服务器名称和上游工具名称。例如，github__create_issue 表示 AISIX 会把调用路由到名为 github 的已注册 MCP Server，并调用它的上游工具 create_issue。已注册的服务器名称不能包含 __，因为 AISIX 会保留该分隔符用于 MCP 工具路由。

这个双下划线分隔符只用于聚合后的 MCP 工具名称。普通字段名仍然使用单下划线，例如 display_name 和 allowed_tools。

下面的流程展示了 3 个已注册的上游 MCP Server，以及 MCP 客户端通过 AISIX 能看到的带前缀工具名：

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

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可被网关通过 Streamable HTTP 访问的上游 MCP Server。
一个 MCP 客户端会发送给 AISIX 的调用方 API Key 值。

注册上游 MCP Server

为上游端点创建 MCP Server 资源：

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
  }'

AISIX 会将上游凭证保存到 MCP Server 资源中。MCP 客户端发送的调用方 API Key 用于认证到 AISIX，而不是认证到上游 MCP Server。

授权工具访问

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

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

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

使用允许的工具名称创建 API Key 资源。如果该 Key 只用于 MCP 流量，可以使用空的模型允许列表：

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

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

请为调用方选择尽可能小的工具访问范围：

工具访问设置	行为
具体工具名称	只允许列出的工具，例如 `github__create_issue`。
`["*"]`	允许访问所有已注册 MCP Server 的所有工具。
省略、`null` 或 `[]`	不允许访问任何 MCP 工具。

上面的示例展示了基础 MCP 设置所需的字段。完整资源 schema 请参见 Admin API 参考。

连接 MCP 客户端

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

如果你的 MCP 客户端接受 JSON 配置，可以将这些值映射到客户端自己的 schema。不同客户端的字段名可能不同：

{
  "mcpServers": {
    "aisix": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "Streamable HTTP",
      "headers": {
        "Authorization": "Bearer YOUR_CALLER_API_KEY"
      }
    }
  }
}

客户端连接后，在客户端中列出工具。响应只会包含调用方 API Key 被允许访问的工具。工具调用使用带前缀的工具名，例如 github__create_issue。

应用流量控制

MCP 工具调用与模型请求使用同一个调用方 API Key 边界。在托管部署中，也可以应用 AISIX Cloud 预算检查。

AISIX 会将这些控制应用到 tools/call 请求。即使调用方达到工具调用限流，MCP 握手和工具发现方法仍然可以连接并列出可用工具。

如需限制一个调用方每分钟只能调用一次 MCP 工具，请使用限流配置更新调用方 API Key 资源。更新会替换资源，因此需要包含现有的 Key 哈希和工具访问字段：

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"],
    "rate_limit": {
      "rpm": 1
    }
  }'

更新后，MCP 客户端仍然可以连接并列出被允许的工具。同一分钟内第二次 tools/call 请求会在 AISIX 调用上游 MCP Server 前被 HTTP 429 拒绝。

当 AISIX 需要检查 MCP 工具参数或工具结果时，可以使用安全护栏。安全护栏配置请参见内置关键词安全护栏。

MCP 用量事件会包含入站协议、MCP Server 名称和 MCP 工具名称。由于网关不会在这条路径上计量模型 Token，MCP 工具调用的 Token 和成本字段为 0。

排查工具访问问题

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

MCP Server 资源已启用，且注册的服务器名称没有包含 AISIX 保留给 MCP 工具前缀的 __。
AISIX 网关可以访问上游 MCP Server。
调用方 API Key 的 allowed_tools 中包含准确的带前缀工具名。
MCP 客户端向 AISIX 发送调用方 API Key，而不是上游 MCP 凭证。

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

下一步

继续阅读调用方 API Key来管理调用方凭证，或阅读安全护栏来检查 MCP 工具参数和结果。

MCP Gateway 如何工作​

准备工作​

注册上游 MCP Server​

授权工具访问​

连接 MCP 客户端​

应用流量控制​

排查工具访问问题​

下一步​