# 通过 Apache APISIX 连接 Claude

本指南在 AISIX MCP Gateway 前部署 [Apache APISIX](https://apisix.apache.org/)，通过 [`openid-connect`](https://docs.apiseven.com/hub/openid-connect.md) 插件让用户在 Keycloak 登录，并将 Claude 自定义连接器接入。本指南涵盖两种架构：

|                                    | 网关登录                                                      | Keycloak 签发的 JWT                           |
| ---------------------------------- | ------------------------------------------------------------- | --------------------------------------------- |
| Claude 发送的 Token 由谁签发       | AISIX，在用户登录 Keycloak 之后                               | Keycloak                                      |
| 每个 MCP 请求由谁校验              | AISIX                                                         | APISIX，然后是 AISIX                          |
| APISIX 在哪里运行 `openid-connect` | 只在浏览器登录页上                                            | 每个 MCP 请求上                               |
| 连接器 URL                         | 每个服务器一个，`https://gateway.example.com/ai/mcp/<server>` | 聚合入口 `https://gateway.example.com/ai/mcp` |
| Claude 的 OAuth 客户端             | Claude 自行注册                                               | 你在 Keycloak 中为 Claude 创建的客户端        |
| Keycloak 需要能被谁访问            | 用户浏览器、APISIX 和 AISIX                                   | 用户浏览器、APISIX、AISIX 和 Anthropic 云     |
| 上游收到用户自己的 Token           | 是，来自用户在上游的单独登录                                  | 本指南不涉及                                  |

如果 Keycloak 不能对 Anthropic 云开放、每个用户需要在上游 MCP 服务器使用自己的 Token，或者希望每个服务器一个连接器，请选择网关登录。如果必须由 APISIX 自己对照 Keycloak 校验每个 MCP 请求，且上游服务器不需要用户单独登录，请选择 Keycloak 签发的 JWT。

两种架构是二选一的方案，本指南分别独立配置它们。如果要在同一个 APISIX 主机后同时运行两种架构，请为每种架构使用各自的路径前缀、AISIX 环境、APISIX 上游和路由 ID 以及 MCP 服务器名称，并让两者共用一个打开了 **Standard flow** 的 `apisix-gateway` Keycloak 客户端。这正是验证时使用的布局：网关登录使用 `/ai`，Keycloak 签发的 JWT 使用 `/ai-jwt`。不要让两者共用一个前缀：Keycloak 签发的 JWT 架构中的 Bearer 路由覆盖 `/ai/mcp/*`，其中包括网关登录的单服务器 URL，网关登录随后会按[网关登录后 MCP 调用因 Token 无效而失败](#mcp-calls-fail-with-an-invalid-token-after-gateway-sign-in)中描述的方式失败。

两种配置都已使用 Keycloak 26.8.2 和连接 AISIX Enterprise 的 AISIX 网关 1.10.0 完成端到端验证：在 Apache APISIX 3.20.0 上使用浏览器中的 claude.ai 自定义连接器验证，在 Apache APISIX 3.18.0 上使用按相同流程运行的脚本客户端验证，两者行为一致。交互式登录和带路径前缀的资源 URL 需要 1.9.0 或更高版本的网关。

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始之前，请准备以下内容：

* 一个已接入网关的 AISIX Enterprise 或 AISIX Cloud 环境，并具备管理环境、OIDC 身份提供方、MCP 服务器、调用方 API Key 和 Claim 映射的权限。按 [MCP 交互式登录](https://docs.apiseven.com/ai-gateway/mcp-gateway/interactive-sign-in.md#aisix-enterprise-or-aisix-cloud)中的方式导出 `AISIX_CP`、`AISIX_TOKEN` 和 `ENV_ID`。
* 一个提供 Streamable HTTP 的上游 MCP 服务器。网关登录架构还要求上游接受 Keycloak 的 Access Token。
* Keycloak Realm 的管理员权限。本指南使用位于 `https://sso.example.com/realms/example` 的 Realm `example`。
* 一套启用了 Admin API、可通过 `https` 从互联网访问的 Apache APISIX。
* 一个可以添加自定义连接器的 Claude 账号。在 Team 和 Enterprise 套餐中，只有组织的 Owner 可以添加。

示例使用以下值，请替换为你自己的值：

| 值                                   | 示例                                     |
| ------------------------------------ | ---------------------------------------- |
| APISIX 的公开源站                    | `https://gateway.example.com`            |
| APISIX 转发到 AISIX 前剥离的路径前缀 | `/ai`                                    |
| APISIX 访问 AISIX 网关的地址         | `aisix.internal:3000`                    |
| Keycloak Issuer                      | `https://sso.example.com/realms/example` |
| AISIX 中的 MCP 服务器名称            | `my-tools`                               |
| AISIX 接受的 Audience                | `aisix`                                  |

导出 APISIX Admin API 的地址和密钥：

```
export APISIX_ADMIN="http://127.0.0.1:9180/apisix/admin"

export APISIX_ADMIN_KEY="YOUR_APISIX_ADMIN_KEY"
```

## 将前缀下的所有请求路由到 AISIX[​](#route-everything-under-the-prefix-to-aisix "将前缀下的所有请求路由到 AISIX的直接链接")

两种架构都从一条兜底路由开始。它把 `/ai` 下的所有请求剥离前缀后发给 AISIX，不运行任何认证插件：

```
curl -sS -X PUT "$APISIX_ADMIN/upstreams/aisix" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "type": "roundrobin",

    "pass_host": "pass",

    "scheme": "http",

    "timeout": {"connect": 5, "send": 300, "read": 300},

    "nodes": {"aisix.internal:3000": 1}

  }'



curl -sS -X PUT "$APISIX_ADMIN/routes/aisix" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "uri": "/ai/*",

    "priority": 0,

    "upstream_id": "aisix",

    "plugins": {

      "proxy-rewrite": {"regex_uri": ["^/ai/(.*)", "/$1"]}

    }

  }'
```

之后，每种架构再为运行 `openid-connect` 的路径或需要特殊处理的发现路径添加优先级更高的路由。

将环境的 MCP 资源 URL 设为聚合入口的公开 URL，包含前缀。两种架构都会用到它：

```
curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{"mcp_resource_url": "https://gateway.example.com/ai/mcp"}'
```

路径必须以 `/mcp` 结尾。在控制台中，该设置是环境 **MCP 访问** 页面上的 **资源 URL**。AISIX 在前缀之后如何发布发现信息，请参见[在按路径前缀路由的网关后运行](https://docs.apiseven.com/ai-gateway/mcp-gateway/client-authentication.md#run-behind-a-path-prefix-gateway)。

## 网关登录[​](#gateway-sign-in "网关登录的直接链接")

在这种架构中，AISIX 通过[交互式登录](https://docs.apiseven.com/ai-gateway/mcp-gateway/interactive-sign-in.md)为 Claude 完成整个 OAuth 流程。Claude 向 AISIX 自行注册，用户在浏览器中登录 Keycloak，AISIX 向 Claude 签发会话 Token。之后，AISIX 使用该用户自己的 Keycloak Token 调用上游。

APISIX 只在 AISIX 的浏览器页面前增加一次 Keycloak 登录，因此没有 Keycloak 会话的用户无法到达 AISIX 的授权页。用户只在 APISIX 这一步输入一次密码，随后 AISIX 的网关登录和上游登录都通过 Keycloak 单点登录完成。

<!-- -->

### 为什么 APISIX 不校验 MCP 调用[​](#why-apisix-does-not-validate-the-mcp-calls "为什么 APISIX 不校验 MCP 调用的直接链接")

在这种架构中，APISIX 无法校验 Claude 发送的 Token。AISIX 签发的会话 Token 以 `aisix_mcp_at_` 开头，由网关用自己的密钥加密，不是 Keycloak 签名的 JWT，Keycloak 也无法对它做 Introspection。如果在 MCP 路径上开启 `bearer_only`，APISIX 会以 `401` 拒绝每个 MCP 调用。因此，MCP 路径、发现、客户端注册和 Token 端点都要留在兜底路由上，由 AISIX 自己校验每个 MCP 调用。

### 创建 Keycloak 客户端[​](#create-the-keycloak-clients "创建 Keycloak 客户端的直接链接")

在 Realm 中创建三个 OpenID Connect 客户端。每个客户端都进入 **Clients** > **Create client**，**Client type** 保持 **OpenID Connect**，填写 **Client ID** 后选择 **Next**。在 **Capability config** 中打开 **Client authentication**，**Standard flow** 保持打开。**Direct access grants** 默认关闭，保持关闭即可。选择 **Next**，在 **Valid redirect URIs** 中填写重定向 URI，然后选择 **Save**。在 **Credentials** 标签页的 **Client Secret** 字段复制各自的密钥。

| 客户端 ID           | 有效的重定向 URI                                           | 使用方                                 |
| ------------------- | ---------------------------------------------------------- | -------------------------------------- |
| `apisix-gateway`    | `https://gateway.example.com/ai/mcp-oauth/apisix-callback` | 浏览器页面上的 APISIX `openid-connect` |
| `aisix-login`       | `https://gateway.example.com/ai/mcp-oauth/login/callback`  | AISIX 网关登录                         |
| `my-tools-upstream` | `https://gateway.example.com/ai/mcp-oauth/callback`        | AISIX 在上游 MCP 服务器的登录          |

为 `aisix-login` 和 `my-tools-upstream` 各添加一个 Audience Mapper。进入 **Clients** > 该客户端 > **Client scopes** > `<client>-dedicated` > **Configure a new mapper** > **Audience**。填写 **Name**（例如 `aisix-audience`），设置 **Included Custom Audience**，**Add to access token** 默认已打开，保持打开，然后选择 **Save**：

* `aisix-login` 使用 AISIX 接受的 Audience `aisix`。
* `my-tools-upstream` 使用上游 MCP 服务器要求的 Audience。

Keycloak 要求填写 **Name**。不填时会显示 **Required field**，Mapper 不会保存：

![Keycloak 中 Audience Mapper 的 Add mapper 表单，已填写 Included Custom Audience，Name 为空并显示 Required field](https://static.api7.ai/uploads/2026/11/17/fEZ9ETmn_keycloak-audience-mapper-name.webp)

### 配置 APISIX[​](#configure-apisix "配置 APISIX的直接链接")

为 AISIX 的授权页及其 `/mcp-oauth/*` 页面（登录回调、上游回调和同意页）添加一条优先级更高的路由：

```
curl -sS -X PUT "$APISIX_ADMIN/routes/aisix-browser-oidc" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "priority": 10,

    "uris": ["/ai/mcp/*", "/ai/mcp-oauth/*"],

    "vars": [["uri", "~~", "^/ai/(mcp/[^/]+/oauth/authorize|mcp-oauth/.*)$"]],

    "upstream_id": "aisix",

    "plugins": {

      "openid-connect": {

        "client_id": "apisix-gateway",

        "client_secret": "YOUR_APISIX_GATEWAY_CLIENT_SECRET",

        "discovery": "https://sso.example.com/realms/example/.well-known/openid-configuration",

        "scope": "openid email profile",

        "bearer_only": false,

        "unauth_action": "auth",

        "use_pkce": true,

        "redirect_uri": "https://gateway.example.com/ai/mcp-oauth/apisix-callback",

        "session": {"secret": "YOUR_RANDOM_SECRET_OF_32_OR_MORE_CHARACTERS"},

        "set_access_token_header": false

      },

      "proxy-rewrite": {"regex_uri": ["^/ai/(.*)", "/$1"]}

    }

  }'
```

* `redirect_uri` 必须位于该路由覆盖的路径上，并且不能是 AISIX 自己的回调 `/mcp-oauth/callback` 或 `/mcp-oauth/login/callback`。
* `set_access_token_header: false` 让插件不把 APISIX 会话的 Access Token 写入转发给 AISIX 的请求。

### 配置 AISIX[​](#configure-aisix "配置 AISIX的直接链接")

导出客户端密钥：

```
export AISIX_LOGIN_CLIENT_SECRET="YOUR_AISIX_LOGIN_CLIENT_SECRET"

export UPSTREAM_CLIENT_SECRET="YOUR_MY_TOOLS_UPSTREAM_CLIENT_SECRET"
```

创建带网关登录的 OIDC 身份提供方：

```
curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/oidc_providers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "keycloak",

    "issuer": "https://sso.example.com/realms/example",

    "audiences": ["aisix"],

    "login": {

      "client_id": "aisix-login",

      "client_secret": "'"$AISIX_LOGIN_CLIENT_SECRET"'",

      "scopes": ["email", "profile"]

    }

  }'
```

创建需要用户在上游单独登录的 MCP 服务器：

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "my-tools",

    "type": "mcp",

    "url": "https://tools.internal.example.com/mcp",

    "auth_type": "oauth2_authorization_code",

    "client_id": "my-tools-upstream",

    "secret": "'"$UPSTREAM_CLIENT_SECRET"'",

    "authorization_url": "https://sso.example.com/realms/example/protocol/openid-connect/auth",

    "token_url": "https://sso.example.com/realms/example/protocol/openid-connect/token",

    "scopes": [],

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

创建已登录用户所使用的调用方 API Key，并将 Realm 中的所有用户映射到它：

```
export API_KEY_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "display_name": "my-tools-users",

    "allowed_models": [],

    "mcp_access": {"allow": ["my-tools__*"]}

  }' | jq -r '.api_key.id')



curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/claim_mappings" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "realm-users",

    "jwt_provider": "keycloak",

    "priority": 100,

    "match": [

      {"claim": "iss", "op": "exact", "values": ["https://sso.example.com/realms/example"]}

    ],

    "resolve": {"api_key_id": "'"$API_KEY_ID"'"}

  }'
```

如需为不同用户授予不同权限，请改为匹配群组或其他 Claim，参见 [JWT Claim 映射](https://docs.apiseven.com/ai-gateway/traffic-controls/claim-mappings.md)。

在控制台中，**OIDC 身份提供方** 页面的提供方表单有 **网关登录（可选）** 一节，MCP 服务器表单的认证类型提供 **OAuth 2.0（用户各自登录）**。

### 在 Claude 中添加连接器[​](#add-the-connector-in-claude "在 Claude 中添加连接器的直接链接")

可以在 claude.ai 或 Claude 桌面应用中添加连接器。自定义连接器按 URL 添加，不绑定某个应用。以下步骤在浏览器中的 claude.ai 上验证。

1. 进入 **Customize** > **Connectors**，选择 **+ Add**，再选择 **Add custom connector**。在 Team 和 Enterprise 套餐中，由 Owner 在 **Organization settings** > **Connectors** 中选择 **Add**，再选择 **Custom** > **Web** 添加连接器，成员随后在 **Customize** > **Connectors** 中连接。

2. 在 **Add custom connector** 对话框中填写名称（显示在连接器列表中）和单服务器 URL `https://gateway.example.com/ai/mcp/my-tools`，选择 **Continue**。

   ![Add custom connector 对话框，填写了连接器名称和 URL https://gateway.example.com/ai/mcp/my-tools](https://static.api7.ai/uploads/2026/11/17/RBrFwn3D_gateway-sign-in-add-connector-trimmed.webp)

3. Claude 会检查服务器并标出检测到的选项。**Authentication** 保持 **Sign in now**，**OAuth client** 保持 **Register automatically**，两者都标有 **Detected**，这样 Claude 会向 AISIX 自行注册。选择 **Add**。

   ![Add custom connector 对话框第二页，选中 Sign in now 和 Register automatically，两者都标有 Detected](https://static.api7.ai/uploads/2026/11/17/0KECVsFL_gateway-sign-in-connector-options-trimmed.webp)

4. 连接器显示尚未连接。选择 **Connect**。

   ![连接器页面，显示 URL、尚未连接的提示和 Connect 按钮](https://static.api7.ai/uploads/2026/11/17/IZ5H4I3z_gateway-sign-in-connect.webp)

5. 浏览器经 APISIX 路由打开 Keycloak 的 **Sign in to your account** 页面。登录后，AISIX 的网关登录和上游登录通过 Keycloak 单点登录完成，不会再次提示。

   ![Keycloak 的 Sign in to your account 页面，包含 Username or email 和 Password 输入框](https://static.api7.ai/uploads/2026/11/17/e5lY5y1q_gateway-sign-in-keycloak.webp)

6. 流程最后停在 AISIX 的 **Allow access to this MCP server?** 页面，页面显示 MCP 服务器、已登录用户和应用地址 `https://claude.ai`。选择 **Allow**。

   ![AISIX 同意页 Allow access to this MCP server，MCP 服务器为 my-tools，应用地址为 https://claude.ai，已登录用户已遮盖](https://static.api7.ai/uploads/2026/11/17/5L87JLUn_gateway-sign-in-consent.webp)

7. 连接器已连接，并在 **Tool permissions** 下列出服务器的工具。单服务器连接器按工具自己的名称列出每个工具，例如 `get_weather` 显示为 **Get weather**。

   ![已连接的连接器，带 Disconnect 按钮，Tool permissions 下列出 Get weather 工具，权限为 Needs approval](https://static.api7.ai/uploads/2026/11/17/s4Yj9w7k_gateway-sign-in-tools.webp)

8. 让 Claude 使用某个工具。默认权限为 **Needs approval**，Claude 每次调用前都会询问。选择 **Allow once** 或 **Always allow**。

   ![Claude 请求使用连接器中的 Get weather，提供 Deny、Always allow 和 Allow once 按钮](https://static.api7.ai/uploads/2026/11/17/FGK4758a_gateway-sign-in-approve.webp) ![Claude 使用连接器后回答台北目前晴，气温 24 摄氏度](https://static.api7.ai/uploads/2026/11/17/HQLQQZIc_gateway-sign-in-answer.webp)

每个 MCP 服务器添加一个连接器。每个单服务器 URL 都是独立的 OAuth 资源，会话只在签发它的服务器上有效。

## Keycloak 签发的 JWT[​](#keycloak-issued-jwt "Keycloak 签发的 JWT的直接链接")

在这种架构中，Claude 让用户在 Keycloak 登录，并在每个 MCP 请求中发送 Keycloak 的 Access Token。APISIX 在转发前对照 Keycloak 的签名密钥校验该 JWT，AISIX 再按自己的 OIDC 身份提供方校验一次。

<!-- -->

### 要求[​](#requirements "要求的直接链接")

* **连接器 URL 是聚合入口** `https://gateway.example.com/ai/mcp`。Claude 要求受保护资源元数据中的 `resource` 与连接器 URL 相同，而 AISIX 为 JWT 发现发布的资源 URL 以 `/mcp` 结尾。工具在 Claude 中显示为 `<server>__<tool>`，例如 `my-tools__get_weather`。
* **Keycloak 必须能被 Anthropic 云访问**。 Claude 从 Anthropic 的服务器到 Keycloak 的 Token 端点兑换授权码，其出口地址段为 `160.79.104.0/21`。
* **身份提供方需要配置 `required_scopes`**。 不配置时，AISIX 发布的受保护资源元数据不列出任何 Scope，Claude 会请求 Keycloak 发现文档公布的所有 Scope。由于其中有些 Scope 没有分配给该客户端，Keycloak 会以 `invalid_scope` 拒绝请求，Claude 显示 `Authorization with <name> failed. You can check your credentials and permissions.`。按下文配置一个专用的 Client Scope 即可避免。

### 创建 Keycloak Client Scope 和客户端[​](#create-the-keycloak-client-scope-and-clients "创建 Keycloak Client Scope 和客户端的直接链接")

1. 创建 Client Scope `aisix-mcp`：进入 **Client scopes** > **Create client scope**，将 **Name** 设为 `aisix-mcp`，**Type** 设为 **None**，**Protocol** 设为 **OpenID Connect**，打开 **Include in token scope** 并保存。

2. 为 Claude 创建客户端 `claude-connector`：进入 **Clients** > **Create client**，保持 **OpenID Connect** 并填写客户端 ID。在 **Capability config** 中打开 **Client authentication**，**Standard flow** 保持打开，并打开 **Require PKCE**。随后出现 **PKCE Method**，值为 **S256**，保持不变。在 **Valid redirect URIs** 中添加 `https://claude.ai/api/mcp/auth_callback` 并保存。对已有的客户端，这些开关位于 **Settings** 标签页的 **Capability config** 中：

   ![Keycloak 客户端的 Capability config，Require PKCE 已打开，PKCE Method 为 S256](https://static.api7.ai/uploads/2026/11/17/wtIVgIkG_keycloak-require-pkce.webp)

   然后：

   * 在 **Client scopes** 标签页中选择 **Add client scope**，选中 `aisix-mcp`，再选择 **Add** > **Default**。保留 `offline_access` 的分配（它默认就是可选 Scope），因为 Claude 也会请求它。
   * 在 **Client scopes** > `claude-connector-dedicated` 中选择 **Configure a new mapper** > **Audience**。填写 **Name**，将 **Included Custom Audience** 设为 `aisix`，**Add to access token** 保持打开，然后保存。
   * 在 **Credentials** 标签页复制密钥。

3. 为 APISIX 创建客户端 `apisix-gateway`，打开 **Client authentication**。**Standard flow** 可以关闭，因为基于 `use_jwks` 的 Bearer 校验并不使用该客户端，但插件的 Schema 仍要求填写 `client_id`。如果同时运行网关登录，请复用网关登录中打开了 **Standard flow** 的 `apisix-gateway` 客户端，不要再创建一个。

### 配置 APISIX[​](#configure-apisix-1 "配置 APISIX的直接链接")

添加三条优先级更高的路由。MCP 路由校验 Bearer JWT，两条发现路由不经过插件直接到达 AISIX：

```
curl -sS -X PUT "$APISIX_ADMIN/routes/aisix-mcp-bearer" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "uris": ["/ai/mcp", "/ai/mcp/*"],

    "priority": 10,

    "upstream_id": "aisix",

    "plugins": {

      "openid-connect": {

        "client_id": "apisix-gateway",

        "client_secret": "YOUR_APISIX_GATEWAY_CLIENT_SECRET",

        "discovery": "https://sso.example.com/realms/example/.well-known/openid-configuration",

        "bearer_only": true,

        "use_jwks": true,

        "claim_validator": {"audience": {"required": true}}

      },

      "proxy-rewrite": {"regex_uri": ["^/ai/(.*)", "/$1"]}

    }

  }'



curl -sS -X PUT "$APISIX_ADMIN/routes/aisix-wellknown" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "uri": "/ai/.well-known/*",

    "priority": 10,

    "upstream_id": "aisix",

    "plugins": {

      "proxy-rewrite": {"regex_uri": ["^/ai/(.*)", "/$1"]}

    }

  }'



curl -sS -X PUT "$APISIX_ADMIN/routes/aisix-root-prm" \

  -H "X-API-KEY: $APISIX_ADMIN_KEY" \

  -d '{

    "uri": "/.well-known/oauth-protected-resource/ai/mcp",

    "priority": 10,

    "upstream_id": "aisix",

    "plugins": {

      "proxy-rewrite": {"uri": "/.well-known/oauth-protected-resource/mcp"}

    }

  }'
```

* 不带 Token 的请求会收到 APISIX 自己的 `401` 和 `WWW-Authenticate: Bearer realm="apisix"`，其中没有 `resource_metadata`。Claude 随后在源站根路径的 `/.well-known/oauth-protected-resource/ai/mcp` 查找元数据，由 `aisix-root-prm` 路由从 AISIX 返回。
* Claude 从 `https://sso.example.com/realms/example/.well-known/openid-configuration` 读取 Keycloak 的元数据。它对 Keycloak 源站根路径下 well-known 路径的请求返回 `404` 不影响使用。
* AISIX 原样收到客户端的 `Authorization: Bearer <JWT>`。在插件默认设置下，APISIX 还会添加 `X-Access-Token` 和 `X-Userinfo`。

### 配置 AISIX[​](#configure-aisix-1 "配置 AISIX的直接链接")

创建 OIDC 身份提供方，并将专用 Scope 设为 `required_scopes`：

```
curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/oidc_providers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "keycloak",

    "issuer": "https://sso.example.com/realms/example",

    "audiences": ["aisix"],

    "required_scopes": ["aisix-mcp"]

  }'
```

此后，AISIX 发布的受保护资源元数据会列出 `scopes_supported: ["aisix-mcp"]`。Claude 请求 `aisix-mcp offline_access`，Keycloak 接受该请求。在控制台中，这是 **OIDC 身份提供方** 页面上提供方的 **必需 scope（可选）** 字段。

`required_scopes` 作用于 AISIX 按该身份提供方校验的每个 Token，而不只是 Claude 的 Token。其他通过同一身份提供方调用 AISIX 的 Keycloak 客户端也需要 `aisix-mcp`。网关登录同样会请求身份提供方的 `required_scopes`，并拒绝未被授予这些 Scope 的登录，因此如果该身份提供方也配置了 `login`，还要把 `aisix-mcp` 分配给它的 `login` 客户端。

注册 MCP 服务器时使用 `oauth2_authorization_code` 以外的 `auth_type`，并允许它在该环境中使用。经过验证的配置使用 `auth_type: none`：

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "my-tools",

    "type": "mcp",

    "url": "https://tools.internal.example.com/mcp",

    "auth_type": "none",

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

MCP 服务器名称在组织内唯一。如果网关登录已经注册了 `my-tools`，请用其他名称注册这个服务器，例如 `my-tools-jwt`，并在调用方 API Key 的 `mcp_access` 中使用该名称，例如 `my-tools-jwt__*`。它的工具随后显示为 `my-tools-jwt__get_weather`。

然后按[网关登录架构](#configure-aisix)中的方式创建调用方 API Key 和 Claim 映射。

### 在 Claude 中添加连接器[​](#add-the-connector-in-claude-1 "在 Claude 中添加连接器的直接链接")

与网关登录相同，可以在 claude.ai 或 Claude 桌面应用中添加连接器。以下步骤在浏览器中的 claude.ai 上验证。

1. 进入 **Customize** > **Connectors**，选择 **+ Add**，再选择 **Add custom connector**。在 Team 和 Enterprise 套餐中，按[网关登录](#add-the-connector-in-claude)中的方式由 Owner 添加。

2. 在 **Add custom connector** 对话框中填写名称和聚合 URL `https://gateway.example.com/ai/mcp`，选择 **Continue**。

   ![Add custom connector 对话框，填写了连接器名称和 URL https://gateway.example.com/ai/mcp](https://static.api7.ai/uploads/2026/11/17/VSJ9qWy6_jwt-add-connector-trimmed.webp)

3. **Authentication** 保持 **Sign in now**。在 **OAuth client** 下选择 **Use your own OAuth client**，即使 **Register automatically** 标有 **Detected**。在 **OAuth client ID** 中填写 `claude-connector`，在 **OAuth client secret (optional)** 中填写该客户端的密钥。该客户端打开了 **Client authentication**，因此 Keycloak 要求提供密钥。选择 **Add**。

   ![Add custom connector 对话框第二页，选中 Sign in now 和 Use your own OAuth client，OAuth client ID 为 claude-connector，密钥字段已遮盖](https://static.api7.ai/uploads/2026/11/17/h8ZOcMcX_jwt-connector-options-trimmed.webp)

4. 在连接器上选择 **Connect**。浏览器会打开 Keycloak 登录页。用户登录（如果 Keycloak 要求，还需同意授权）后，连接器即连接成功。已有 Keycloak 会话的用户不会看到提示。

5. 连接器在 **Tool permissions** 下列出工具。在聚合 URL 上，每个工具都命名为 `<server>__<tool>`，Claude 以易读的形式显示该名称。验证时服务器注册为 `my-tools-jwt`，`my-tools-jwt__get_weather` 显示为 **My-tools-jwt get weather**。

   ![已连接的连接器，Tool permissions 下列出工具 My-tools-jwt get weather](https://static.api7.ai/uploads/2026/11/17/OauFpuB1_jwt-tools.webp)

6. 让 Claude 使用某个工具，并按网关登录中的方式批准调用。

   ![Claude 使用连接器后回答台北目前晴，气温 24 摄氏度](https://static.api7.ai/uploads/2026/11/17/8B3GfRRG_jwt-answer.webp)

## AISIX 如何识别用户[​](#how-aisix-identifies-the-user "AISIX 如何识别用户的直接链接")

在两种架构中，已登录的用户都以 Claim 映射选中的调用方 API Key 运行，AISIX 另外单独记录该用户自己的身份：

* 使用网关登录时，Claude 出示 AISIX 会话 Token。AISIX 在用户完成网关登录时从 Keycloak 取得了用户身份。
* 使用 Keycloak 签发的 JWT 时，AISIX 按 OIDC 身份提供方校验 `Authorization` 中的 Keycloak Access Token。

每次 MCP `tools/call` 都会写入一条用量事件，在 `jwt_subject` 中记录用户身份，同时在 `jwt_provider` 中记录 OIDC 身份提供方，在 `jwt_claim_mapping` 中记录 Claim 映射。使用默认的 `identity_claim` 时，`jwt_subject` 是 Keycloak 用户的 `sub`。`initialize` 和 `tools/list` 不写入用量事件。MCP 工具调用不产生 Token 成本，因此按调用次数归属，而不是按花费。

要列出某个用户的调用，可按 `jwt_subject` 筛选用量事件，例如 `GET /environments/{env_id}/usage_events?jwt_subject=<sub>`。要按用户属性汇总用量，可以让 OIDC 身份提供方把某个 Claim 读入成本归属标签，参见[从 JWT Claim 读取标签](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md#read-tags-from-jwt-claims)。

## 故障排查[​](#troubleshooting "故障排查的直接链接")

### 网关登录后 MCP 调用因 Token 无效而失败[​](#mcp-calls-fail-with-an-invalid-token-after-gateway-sign-in "网关登录后 MCP 调用因 Token 无效而失败的直接链接")

在网关登录架构中，登录成功，但第一个 MCP 调用收到 `401` 和 `WWW-Authenticate: Bearer realm="apisix", error="invalid_token"`，APISIX 也没有把它转发给 AISIX。

原因是 MCP 路径上配置了带 `bearer_only` 的 `openid-connect`。APISIX 请 Keycloak 对 Token 做 Introspection，而该 Token 是 AISIX 会话 Token，并非 Keycloak 签发，Keycloak 因此返回 `active: false`。请从 MCP 路径上移除该插件，参见[为什么 APISIX 不校验 MCP 调用](#why-apisix-does-not-validate-the-mcp-calls)。

### APISIX 使用 Introspection 时拒绝 Keycloak Token[​](#apisix-rejects-keycloak-tokens-when-it-uses-introspection "APISIX 使用 Introspection 时拒绝 Keycloak Token的直接链接")

在 Keycloak 签发 JWT 的架构中，如果插件既没有设置 `use_jwks` 也没有设置 `public_key`，APISIX 会通过 Keycloak 的 Introspection 校验 Token，此时每个 MCP 调用都会收到 APISIX 返回的 `401` 和 `error="invalid_token"`。Keycloak 26.8.2 拒绝对 Audience 中不包含 APISIX 客户端的 Token 做 Introspection，并记录 `Client '<apisix client>' is not in the token audience`。

请像上文的路由那样设置 `use_jwks: true`，让 APISIX 在本地校验 Token。也可以在 Claude 客户端上添加 Audience Mapper，把 APISIX 客户端加入 Token 的 Audience。

### 登录后 Claude 报告服务拒绝了它的请求[​](#claude-reports-that-the-service-refused-its-request-after-sign-in "登录后 Claude 报告服务拒绝了它的请求的直接链接")

Claude 显示 `You signed in to <name>, but it then refused Claude's request. Your account there may not allow access from Claude, or a firewall may be blocking Claude.`，且没有任何携带凭据的 MCP 请求到达 APISIX。

原因是 APISIX 前面的 WAF、CDN 或 Bot 管理规则拦截了 User-Agent 为 `Claude-User` 的请求。Claude 的发现、客户端注册和 Token 请求使用另一个 User-Agent，可以通过；而每个携带凭据的 MCP 调用都带有 `Claude-User`，在到达 APISIX 之前就被拦截。请让 MCP 路径免于 AI Bot 规则，或放行 Anthropic 的出口地址段 `160.79.104.0/21`。

### Claude 报告授权失败[​](#claude-reports-that-authorization-failed "Claude 报告授权失败的直接链接")

在 Keycloak 签发 JWT 的架构中，Claude 显示 `Authorization with <name> failed. You can check your credentials and permissions.`，Keycloak 为 Claude 客户端记录一条带 `Invalid scopes` 的 `LOGIN_ERROR`。

原因是身份提供方没有配置 `required_scopes`，Claude 请求了 Keycloak 公布的所有 Scope。请按 [Keycloak 签发的 JWT](#keycloak-issued-jwt) 中的说明配置专用 Client Scope 和 `required_scopes`。

### 浏览器被重定向到旧的 Keycloak 地址[​](#browsers-are-sent-to-an-old-keycloak-address "浏览器被重定向到旧的 Keycloak 地址的直接链接")

APISIX `openid-connect` 会缓存身份提供方的发现文档。修改 Keycloak 的公开主机名后，APISIX 在重启之前一直把浏览器重定向到旧主机名。做出此类修改后，请重新加载或重启 APISIX。

### APISIX 不校验 Audience 的值[​](#audience-values-are-not-checked-by-apisix "APISIX 不校验 Audience 的值的直接链接")

`claim_validator.audience.required: true` 只检查 Token 是否带有 `aud` Claim。只有打开 `match_with_client_id` 时，APISIX 才比较其值，而且是与自己的 `client_id` 比较。请通过 AISIX 中身份提供方的 `audiences` 强制校验 Audience 的值：`aud` 与其中任何一个都不匹配的 Token 会被拒绝。

### 请求头选项不影响 Bearer 校验[​](#header-options-do-not-change-bearer-validation "请求头选项不影响 Bearer 校验的直接链接")

`access_token_in_authorization_header`、`set_access_token_header`、`set_userinfo_header` 以及插件其他 `set_*_header` 选项只控制 APISIX 在转发的请求中添加哪些请求头，不影响 `bearer_only` 如何校验 Token。

## 限制[​](#limitations "限制的直接链接")

* 在 Keycloak 签发 JWT 的架构中，本指南不涉及把用户的 Keycloak Token 继续传给要求该 Token 的上游 MCP 服务器。经过验证的上游不需要认证。
* 在经过验证的运行中，Keycloak 为 Claude 签发了离线 Refresh Token，但测试时间窗口内没有观察到 Token 刷新。

## 后续步骤[​](#next-steps "后续步骤的直接链接")

* [MCP 交互式登录](https://docs.apiseven.com/ai-gateway/mcp-gateway/interactive-sign-in.md)：网关登录中的会话、拒绝情形以及断开用户连接。
* [客户端身份认证](https://docs.apiseven.com/ai-gateway/mcp-gateway/client-authentication.md)：OAuth 发现以及客户端认证的其他方式。
* [Keycloak 集成](https://docs.apiseven.com/ai-gateway/traffic-controls/keycloak-integration.md)：将 Keycloak 群组和属性映射到调用方 API Key。
* [控制 MCP 工具访问](https://docs.apiseven.com/ai-gateway/mcp-gateway/tool-access-control.md)：限制某个 Key 可以调用的工具。
