MCP 网关概览
AISIX AI 网关可以把已注册的上游 MCP（Model Context Protocol）Server 暴露为一个统一的 MCP 端点。Agent 连接到 AISIX 后，只能发现并调用其调用方 API Key 允许访问的工具，并且不会拿到上游 MCP Server 的凭证。
这让工具调用流量与模型流量使用同一个认证、访问控制、策略和遥测边界。一个调用方 API Key 可以同时控制允许使用的模型和允许调用的 MCP 工具。AISIX 会认证调用方、检查工具访问权限、应用流量控制和安全护栏，然后用你配置的上游凭证把调用转发到注册的 MCP Server，并记录 MCP 工具调用遥测。
深入了解各主题请参见：
- 上游认证：AISIX 如何使用
none、bearer、api_key或oauth2认证到上游 MCP Server。 - 按 Key 控制工具访问：调用方 API Key 上的
allowed_tools如何决定该 Key 可以列出和调用哪些工具。
MCP 网关如何工作
每个上游 MCP Server 都会注册为一个网关资源。AISIX 根据注册名称为该 Server 的工具添加前缀。
AISIX 使用两个下划线分隔注册的 Server 名称和上游工具名称。例如，github__create_issue 会路由到名为 github 的 MCP Server，并调用其上游工具 create_issue。注册名称不能包含 __，因为 AISIX 会保留该分隔符用于 MCP 工具路由。
MCP 客户端连接 AISIX 代理监听器上的 /mcp。上游 MCP Server 必须使用 Streamable HTTP transport。
准备工作
请先准备以下内容：
- 一个 Admin 和 代理监听器都可用的自托管 AISIX 网关。
- 网关
config.yaml中的 Admin Key。 - 一个网关可访问的 Streamable HTTP 上游 MCP Server。
- 一个 MCP 客户端将发送给 AISIX 的调用方 API Key。
在 AISIX Cloud 中，你可以在 Dashboard 中注册 MCP Server 并授予工具访问权限；这些配置以组织为范围，并按环境暴露。概念相同，只是管理界面不同。请参见 AISIX Cloud。
注册上游 MCP Server
下面示例使用 bearer token 认证上游。其它认证模式请参见上游认证。
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 | 该 Server 的工具名前缀，不能为空，且不能包含保留分隔符 __。 |
url | 上游 MCP 端点。 |
transport | 默认为 streamable_http，也是当前唯一支持的 transport。 |
auth_type | AISIX 认证上游的方式：none、bearer、api_key 或 oauth2。 |
secret | 所选 auth_type 的上游凭证。该字段只写入，AISIX 不会在读取响应中返回明文。 |
timeout_ms | 单次上游请求超时时间。 |
enabled | 是否分发到该 Server，默认 true。设置为 false 可以保留注册但停止暴露其工具。 |
授予工具访问权限
MCP 客户端只能看到并调用其调用方 API Key 允许的工具。创建 API Key 资源前，请先对明文调用方 Key 计算哈希：
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')
创建只用于 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__*"]
}'
["github__*"] 会授权访问 github Server 上的全部工具。只授 权单个工具时，请填写完整的前缀工具名；授权全部工具时使用 ["*"]。匹配规则请参见按 Key 控制工具访问。
连接 MCP 客户端
把 MCP 客户端或 agent 配置为通过 Streamable HTTP 连接 AISIX 代理端点 /mcp，并在 Authorization 请求头中发送调用方 API Key：
{
"mcpServers": {
"aisix": {
"url": "http://127.0.0.1:3000/mcp",
"transport": "Streamable HTTP",
"headers": {
"Authorization": "Bearer YOUR_CALLER_API_KEY"
}
}
}
}
连接后，从客户端列出工具。预期结果是：工具列表只包含调用方 API Key 允许访问的工具，例如所有 github__* 工具。
应用流量控制
MCP 工具调用会经过与模型请求相同的调用方 API Key 边界，因此可以应用相同的控制能力：
- 限流和预算：AISIX 对
tools/call请求应用限流。MCP 握手和tools/list即使在达到工具调用限流后仍可连接和列出工具。 - 安全护栏：安全护栏可以检查 MCP 工具调用参数和工具结果。被阻断的调用会以 MCP 错误拒绝，且不会发送到上游。
- 遥测：MCP 用量事件会记录入站协议、MCP Server 名称和 MCP 工具名。工具调用路径不计量模型 token，因此 token 和费用字段为零。
排查工具访问问题
如果客户端看不到或无法调用某个工具，请检查 MCP Server 是否启用、上游是否可达、认证是否有效，以及调用方 API Key 的 allowed_tools 是否覆盖该前缀工具名。