上游身份认证

每个已注册的 MCP 服务器都可以定义 AISIX 如何向上游服务器执行身份认证。AISIX 在网关侧持有所有上游凭证，并在列出工具或转发工具调用时提供该凭证。MCP 客户端发送给 AISIX 的调用方 API Key 用于向 AISIX 认证调用方，永远不会转发或公开给上游 MCP 服务器。

使用 auth_type 字段和对应身份认证模式要求的字段设置凭证。AISIX Cloud 与开源 AISIX 网关通过不同的管理路径支持相同的模式。

前置条件

开始前，请准备以下环境：

对于 AISIX Cloud，准备一个环境和写入作用域管理员 Token。对于本地部署，请按照 AISIX Cloud 快速入门操作。若要申请混合云访问权限，请联系 API7。
对于开源 AISIX 网关，准备一个加载声明式资源文件的网关。设置 MCP 网关提供了可运行的 MCP 服务器条目以及验证和重新加载工作流。
AISIX Cloud 示例需要 cURL。

身份认证模式

选择与上游 MCP 服务器期望 AISIX 使用的身份认证方式相匹配的模式：

`auth_type`	上游凭证	AISIX 的提供方式
`none`	无	不发送凭证。
`bearer`	`secret` 中的 Bearer Token	`Authorization: Bearer <secret>`
`api_key`	`secret` 中的 API Key	`x-api-key: <secret>`
`oauth2`	`client_id` + `token_url` + `secret`	AISIX 获取访问 Token，然后发送 `Authorization: Bearer <access_token>`。

secret 保存 AISIX 提供给上游的明文凭证。该值仅在网关侧使用，永远不会发送给调用客户端。若要轮换凭证，请使用新的 secret 更新资源。

配置上游身份认证

请通过与你的部署对应的管理路径配置上游身份认证。

AISIX Cloud

AISIX Cloud Admin API 会同时创建服务器及其上游凭证。allowed_environments 列出接收该服务器的环境。列表为空或缺失时，服务器不会公开给任何环境，因此以下每个示例都包含目标环境。

导出控制面连接值：

# AISIX_CP 包含 /api，末尾不带斜杠。
# 本地部署快速入门使用 http://localhost:8080/api。
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

无身份认证

上游 MCP 服务器不要求凭证时使用 none，例如只能通过受信任内部网络访问的服务器。

以下示例创建不带上游凭证的服务器资源：

curl -sS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "runbooks",
    "url": "https://runbooks.internal/mcp",
    "auth_type": "none",
    "allowed_environments": ["'"$ENV_ID"'"]
  }'

auth_type 默认为 none，因此也可以省略。对于 none 服务器，不要设置 secret、client_id、token_url 和 scopes。

Bearer Token

上游服务器要求在 Authorization 请求头中提供静态 Token 时使用 bearer。

以下示例创建服务器资源，并配置 AISIX 应发送给上游的 Bearer Token：

curl -sS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "url": "https://mcp.example.com/mcp",
    "auth_type": "bearer",
    "secret": "YOUR_UPSTREAM_MCP_TOKEN",
    "allowed_environments": ["'"$ENV_ID"'"]
  }'

❶ bearer 会在发送给此上游的每个请求上添加 Authorization: Bearer <secret>。

❷ secret 为必填字段，且不能为空。

API Key

上游服务器要求在 x-api-key 请求头中提供 Key 时使用 api_key。

以下示例创建服务器资源，并配置 AISIX 应发送给上游的 API Key：

curl -sS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "catalog",
    "url": "https://catalog.example.com/mcp",
    "auth_type": "api_key",
    "secret": "YOUR_UPSTREAM_API_KEY",
    "allowed_environments": ["'"$ENV_ID"'"]
  }'

❶ api_key 会在发送给此上游的每个请求上添加 x-api-key: <secret>。

❷ secret 为必填字段，且不能为空。

OAuth 2.0 客户端凭证

上游服务器接受 OAuth 2.0 访问 Token，且你拥有其机器到机器客户端凭证时使用 oauth2。

AISIX 在 Token 端点交换客户端凭证，把访问 Token 发送给上游，并在临近过期前复用该 Token。如果上游服务器因未授权而拒绝 Token，AISIX 会丢弃缓存的 Token，并在下次调用时获取新 Token。

以下示例创建服务器资源，并配置 AISIX 应对此上游使用的 OAuth 客户端凭证：

curl -sS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders",
    "url": "https://orders.example.com/mcp",
    "auth_type": "oauth2",
    "client_id": "aisix-gateway",
    "token_url": "https://auth.example.com/oauth/token",
    "secret": "YOUR_OAUTH_CLIENT_SECRET",
    "scopes": ["mcp.read", "mcp.write"],
    "allowed_environments": ["'"$ENV_ID"'"]
  }'

❶ oauth2 对此上游使用 OAuth 2.0 客户端凭证授权。

❷ oauth2 服务器必须配置 client_id、token_url 和 secret。

❸ scopes 可选。AISIX 使用空格连接这些值，作为 Token 请求的 scope 参数。

AISIX 把访问 Token 保留在网关侧，永远不会返回给调用方。

开源 AISIX 网关

把身份认证字段添加到 resources.yaml 中的服务器条目。通过环境变量插值提供机密信息，不要把明文凭证写入文件：

resources.yaml
_format_version: "1"

mcp_servers:
  - name: github
    type: mcp
    url: https://mcp.example.com/mcp
    auth_type: bearer
    secret: ${GITHUB_MCP_TOKEN}

在网关进程环境中设置 GITHUB_MCP_TOKEN。对于 none，省略 secret。对于 api_key，同一个 secret 字段会作为 x-api-key 发送。对于 oauth2，添加 client_id、token_url 和 secret，并可选择添加 scopes。

环境变量属于网关进程。正在运行的进程无法接收后来在主机 Shell 中新增或更改的变量。添加或轮换通过环境变量提供的凭证后，请使用新值验证资源文件并重启进程。对于容器，请使用新的环境值重新创建容器。只有当资源文件发生变化，且正在运行的进程已经拥有所有被引用的变量及其预期值时，才使用重新加载。

如果验证或重新加载失败，网关不会应用无效条目；重新加载时会继续提供最后一次有效配置。请参阅 CLI 参考和配置状态。

凭证处理

创建或更新服务器时，AISIX 会根据 auth_type 验证凭证字段。凭证字段无效的服务器会在写入时被拒绝。

如果凭证之后失效（例如机密信息已轮换或撤销），只有该服务器的工具不可用。其他已注册 MCP 服务器会继续工作。AISIX 会记录失败，但不会向调用方 Agent 公开凭证详情。

后续步骤

你现在已经了解 AISIX 如何向上游 MCP 服务器执行身份认证。使用以下指南控制哪些调用方可以访问这些工具，以及如何治理其流量：

控制工具访问：把调用方 API Key 限定到特定工具、整个服务器或所有工具。
限流和预算：应用请求和并发限制，并为 MCP 工具调用配置 AISIX Cloud 预算。
安全护栏：检查 MCP 工具参数和结果。

前置条件​

身份认证模式​

配置上游身份认证​

AISIX Cloud​

无身份认证​

Bearer Token​

API Key​

OAuth 2.0 客户端凭证​

开源 AISIX 网关​

凭证处理​

后续步骤​