通过 Apache APISIX 连接 Claude
本指南在 AISIX MCP Gateway 前部署 Apache APISIX,通过 openid-connect 插件让用户在 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 无效而失败中描述的方式失败。
两种配置都已使用 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 或更高版本的网关。
前置条件
开始之前,请准备以下内容:
- 一个已接入网关的 AISIX Enterprise 或 AISIX Cloud 环境,并具备管理环境、OIDC 身份提供方、MCP 服务器、调用方 API Key 和 Claim 映射的权限。按 MCP 交互式登录中的方式导出
AISIX_CP、AISIX_TOKEN和ENV_ID。 - 一个提供 Streamable HTTP 的上游 MCP 服务器。网关登录架构还要求上游接受 Keycloak 的 Access Token。
- Keycloak Realm 的管理员权限。本指南使用位于
https://sso.example.com/realms/example的 Realmexample。 - 一套启用了 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
两种架构都从一条兜底路由开始。它把 /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 在前缀之后如何发布发现信息,请参见在按路径前缀路由的网关后运行。
网关登录
在这种架构中,AISIX 通过交互式登录为 Claude 完成整个 OAuth 流程。Claude 向 AISIX 自行注册,用户在浏览器中登录 Keycloak,AISIX 向 Claude 签发会话 Token。之后,AISIX 使用该用户自己的 Keycloak Token 调用上游。
APISIX 只在 AISIX 的浏览器页面前增加一次 Keycloak 登录,因此没有 Keycloak 会话的用户无法到达 AISIX 的授权页。用户只在 APISIX 这一步输入一次密码,随后 AISIX 的网关登录和上游登录都通过 Keycloak 单点登录完成。
为什么 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 客户端
在 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 接受的 Audienceaisix。my-tools-upstream使用上游 MCP 服务器要求的 Audience。
Keycloak 要求填写 Name。不填时会显示 Required field,Mapper 不会保存:
配置 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
导出客户端密钥:
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 映射。
在控制台中,OIDC 身份提供方 页面的提供方表单有 网关登录(可选) 一节,MCP 服务器表单的认证类型提供 OAuth 2.0(用户各自登录)。
在 Claude 中添加连接器
可以在 claude.ai 或 Claude 桌面应用中添加连接器。自定义连接器按 URL 添加,不绑定某个应用。以下步骤在浏览器中的 claude.ai 上验证。
-
进入 Customize > Connectors,选择 + Add,再选择 Add custom connector。在 Team 和 Enterprise 套餐中,由 Owner 在 Organization settings > Connectors 中选择 Add,再选择 Custom > Web 添加连接器,成员随后在 Customize > Connectors 中连接。
-
在 Add custom connector 对话框中填写名称(显示在连接器列表中)和单服务器 URL
https://gateway.example.com/ai/mcp/my-tools,选择 Continue。
-
Claude 会检查服务器并标出检测到的选项。Authentication 保持 Sign in now,OAuth client 保持 Register automatically,两者都标有 Detected,这样 Claude 会向 AISIX 自行注册。选择 Add。
-
连接器显示尚未连接。选择 Connect。
-
浏览器经 APISIX 路由打开 Keycloak 的 Sign in to your account 页面。登录后,AISIX 的网关登录和上游登录通过 Keycloak 单点登录完成,不会再次提示。
-
流程最后停在 AISIX 的 Allow access to this MCP server? 页面,页面显示 MCP 服务器、已登录用户和应用地址
https://claude.ai。选择 Allow。
-
连接器已连接,并在 Tool permissions 下列出服务器的工具。单服务器连接器按工具自己的名称列出每个工具,例如
get_weather显示为 Get weather。
-
让 Claude 使用某个工具。默认权限为 Needs approval,Claude 每次调用前都会询问。选择 Allow once 或 Always allow。
每个 MCP 服务器添加一个连接器。每个单服务器 URL 都是独立的 OAuth 资源,会话只在签发它的服务器上有效。
Keycloak 签发的 JWT
在这种架构中,Claude 让用户在 Keycloak 登录,并在每个 MCP 请求中发送 Keycloak 的 Access Token。APISIX 在转发前对照 Keycloak 的签名密钥校验该 JWT,AISIX 再按自己的 OIDC 身份提供方校验一次。
要求
- 连接器 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 和客户端
-
创建 Client Scope
aisix-mcp:进入 Client scopes > Create client scope,将 Name 设为aisix-mcp,Type 设为 None,Protocol 设为 OpenID Connect,打开 Include in token scope 并保存。 -
为 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 中:
然后:
- 在 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 标签页复制密钥。
- 在 Client scopes 标签页中选择 Add client scope,选中
-
为 APISIX 创建客户端
apisix-gateway,打开 Client authentication。Standard flow 可以关闭,因为基于use_jwks的 Bearer 校验并不使用该客户端,但插件的 Schema 仍要求填写client_id。如果同时运行网关登录,请复用网关登录中打开了 Standard flow 的apisix-gateway客户端,不要再创建一个。
配置 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
创建 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。
然后按网关登录架构中的方式创建调用方 API Key 和 Claim 映射。
在 Claude 中添加连接器
与网关登录相同,可以在 claude.ai 或 Claude 桌面应用中添加连接器。以下步骤在浏览器中的 claude.ai 上验证。
-
进入 Customize > Connectors,选择 + Add,再选择 Add custom connector。在 Team 和 Enterprise 套餐中,按网关登录中的方式由 Owner 添加。
-
在 Add custom connector 对话框中填写名称和聚合 URL
https://gateway.example.com/ai/mcp,选择 Continue。
-
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。
-
在连接器上选择 Connect。浏览器会打开 Keycloak 登录页。用户登录(如果 Keycloak 要求,还需同意授权)后,连接器即连接成功。已有 Keycloak 会话的用 户不会看到提示。
-
连接器在 Tool permissions 下列出工具。在聚合 URL 上,每个工具都命名为
<server>__<tool>,Claude 以易读的形式显示该名称。验证时服务器注册为my-tools-jwt,my-tools-jwt__get_weather显示为 My-tools-jwt get weather。
-
让 Claude 使用某个工具,并按网关登录中的方式批准调用。
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 读取标签。
故障排查
网关登录后 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 调用。
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 显示 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 报告授权失败
在 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 中的说明配置专用 Client Scope 和 required_scopes。
浏览器被重定向到旧的 Keycloak 地址
APISIX openid-connect 会缓存身份提供方的发现文档。修改 Keycloak 的公开主机名后,APISIX 在重启之前一直把浏览器重定向到旧主机名。做出此类修改后,请重新加载或重启 APISIX。
APISIX 不校验 Audience 的值
claim_validator.audience.required: true 只检查 Token 是否带有 aud Claim。只有打开 match_with_client_id 时,APISIX 才比较其值,而且是与自己的 client_id 比较。请通过 AISIX 中身份提供方的 audiences 强制校验 Audience 的值:aud 与其中任何一个都不匹配的 Token 会被拒绝。
请求头选项不影响 Bearer 校验
access_token_in_authorization_header、set_access_token_header、set_userinfo_header 以及插件其他 set_*_header 选项只控制 APISIX 在转发的请求中添加哪些请求头,不影响 bearer_only 如何校验 Token。
限制
- 在 Keycloak 签发 JWT 的架构中,本指南不涉及把用户的 Keycloak Token 继续传给要求该 Token 的上游 MCP 服务器。经过验证的上游不需要认证。
- 在经过验证的运行中,Keycloak 为 Claude 签发了离线 Refresh Token,但测试时间窗口内没有观察到 Token 刷新。
后续步骤
- MCP 交互式登录:网关登录中的会话、拒绝情形以及断开用户连接。
- 客户端身份认证:OAuth 发现以及客户端认证的其他方式。
- Keycloak 集成:将 Keycloak 群组和属性映射到调用方 API Key。
- 控制 MCP 工具访问:限制某个 Key 可以调用的工具。