MCP 故障排除

本页面介绍在使用Casdoor内置MCP服务器或当Casdoor作为您自有MCP服务器的OAuth提供商时，常见的问题。

常见错误

401 未授权，来自MCP服务器

症状: MCP 服务器拒绝带有 401 未授权 状态码的请求。

原因：

访问令牌已过期
令牌的 aud（受众）声明与 MCP 服务器的资源 URI 不匹配
请求中缺少 Authorization: Bearer 头部
令牌是为其他资源颁发的

修复方法：

在jwt.io解码您的令牌，并检查exp声明以确认过期时间
验证aud声明与您的MCP服务器URI完全匹配（包括协议、主机和端口）
确保请求中包含标头：Authorization: Bearer YOUR_TOKEN
如果在OAuth期间使用resource参数，请确认其与MCP服务器URI匹配

# Example: Check token claims
curl -X GET https://your-mcp-server.com/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

# If 401, inspect token at jwt.io:
# - exp: 1735689600 (must be in future)
# - aud: "https://your-mcp-server.com" (must match server URI)
# - scope: "read:application" (must include required scopes)

浏览器中的CORS错误

症状: 当MCP客户端尝试连接到Casdoor时，浏览器控制台显示CORS错误。

原因：

Casdoor CORS设置未包含MCP客户端的来源
预检请求被阻止
出于安全考虑，通配符 CORS 已禁用

修复方法：

登录Casdoor管理面板
导航至您的应用配置
将MCP客户端的来源添加到CORS允许的来源字段
包含完整来源：https://client-domain.com（如果非标准端口，需包含协议和端口）
对于本地开发，添加 http://localhost:PORT

# Example CORS configuration:
https://claude.ai
https://cursor.sh
http://localhost:3000

重定向URI不匹配

症状: OAuth 流程因 redirect_uri_mismatch 错误而失败。

原因：

授权请求中的redirect_uri与应用配置不完全匹配
方案不匹配（http 与 https）
端口号缺失或不正确
尾部斜杠不匹配

修复方法：

请从您的授权请求中复制精确的redirect_uri
在Casdoor中，编辑应用配置
将确切的URI添加到“重定向URL”字段（必须逐字符匹配）
确保方案、主机、端口和路径完全匹配

# These are all different redirect URIs:
http://localhost:3000/callback
https://localhost:3000/callback  # Different scheme
http://localhost:3000/callback/  # Trailing slash
http://localhost:3001/callback   # Different port

发现端点404

症状：尝试获取.well-known发现文档时返回404。

原因：

为您的用例使用了错误的发现路径
Casdoor配置未公开发现端点
应用程序未配置为OIDC提供程序

修复方法：

请按顺序尝试以下发现端点：

OAuth 授权服务器元数据（RFC 8414）：

curl https://your-casdoor.com/.well-known/oauth-authorization-server

OpenID Connect 发现：

curl https://your-casdoor.com/.well-known/openid-configuration

OAuth 保护的资源元数据（RFC 9470）：

curl https://your-casdoor.com/.well-known/oauth-protected-resource

对于充当资源服务器的 MCP 服务器，请使用 oauth-protected-resource 端点来公布 OAuth 要求。

DCR 注册被拒绝

症状: 动态客户端注册（DCR）请求失败并出现错误。

原因：

组织已在设置中禁用DCR
注册请求缺少必填字段
软件声明被拒绝或无效
注册端点的速率限制

修复方法：

在Casdoor中导航至您的组织设置
启用动态客户端注册开关
配置允许的重定向 URI 模式以限制客户端 URI

对于注册请求，请包含所有必需的元数据：

{
  "client_name": "My MCP Client",
  "redirect_uris": ["https://client.example.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "client_secret_basic"
}

有关详情，请参阅动态客户端注册。

同意屏幕未显示

症状：OAuth 流程完成，但未显示用户同意屏幕。

原因：

应用的同意政策设置为“从不”
用户此前已授予同意，政策为“一次”
会话身份验证会绕过同意

修复方法：

在Casdoor管理面板中编辑您的应用
将同意策略设置为：
- 始终：在每次授权请求时显示同意
- 仅在首次授权时显示同意（推荐）
保存应用程序配置
如果进行测试，请清除用户的先前同意（撤销应用访问权限）

同意屏幕会显示请求的范围及其在范围配置中的显示名称和描述。

insufficient_scope 错误

症状：MCP 工具调用因 JSON-RPC 错误“insufficient_scope”而失败。

原因：

访问令牌不包含该工具所需的范围
令牌请求的范围不正确
范围名称与服务器预期不符

修复方法：

检查 required_scope 和 granted_scopes 的错误响应：

{
  "error": {
    "code": -32001,
    "message": "insufficient_scope",
    "data": {
      "tool": "add_application",
      "granted_scopes": ["read:application"],
      "required_scope": "write:application"
    }
  }
}

使用所需范围请求新令牌：

curl -X POST https://your-casdoor.com/api/login/oauth/access_token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read:application write:application"

有关范围参考，请参阅授权与范围。

无效目标/资源错误

症状: 授权请求因 invalid_target 或 invalid_resource 错误而失败。

原因：

resource参数不是有效的URI（RFC 8707）
资源URI缺少方案（http://或https://）
资源参数与令牌受众冲突

修复方法：

请确保resource参数为完整URL：

# Correct:
resource=https://your-server.com
resource=https://api.example.com:8080

# Incorrect:
resource=your-server.com        # Missing scheme
resource=localhost:3000         # Missing scheme

resource值将成为访问令牌中的aud声明
资源必须与MCP服务器预期的受众完全匹配

Claude Desktop / 光标连接失败

症状: Claude Desktop 或 Cursor IDE 无法连接到 MCP 服务器，并出现 OAuth 错误。

原因：

MCP 服务器未返回有效的受保护资源元数据 (PRM)
WWW-Authenticate 头部格式错误或缺失
发现端点无法访问
令牌验证失败

修复方法：

验证PRM端点返回有效JSON：

curl https://your-mcp-server.com/.well-known/oauth-protected-resource

预期响应：

{
  "resource": "https://your-mcp-server.com",
  "authorization_servers": [
    "https://your-casdoor.com"
  ]
}

在未授权请求上检查WWW-Authenticate标头:

curl -v https://your-mcp-server.com/api/mcp

预期标头：

WWW-Authenticate: Bearer realm="mcp-server",
  authorization_uri="https://your-casdoor.com/login/oauth/authorize",
  scope="read:application write:application"

使用curl测试完整OAuth流程：

# 1. Get authorization code (requires browser)
# 2. Exchange for token
curl -X POST https://your-casdoor.com/api/login/oauth/access_token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# 3. Test MCP endpoint with token
curl https://your-mcp-server.com/api/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

调试工具

MCP检查器

官方MCP Inspector可帮助您以交互方式测试MCP连接：

npx @modelcontextprotocol/inspector

功能：

交互式工具浏览器与测试
实时 JSON-RPC 请求/响应查看器
OAuth流程测试
连接诊断

测试发现端点

验证每个发现端点返回有效的JSON：

# OAuth Authorization Server
curl -s https://your-casdoor.com/.well-known/oauth-authorization-server | jq

# OIDC Configuration
curl -s https://your-casdoor.com/.well-known/openid-configuration | jq

# Protected Resource (for MCP resource servers)
curl -s https://your-mcp-server.com/.well-known/oauth-protected-resource | jq

检查 JWT 令牌

使用jwt.io解码访问令牌并验证声明：

需检查的关键声明：

aud（受众）：必须与MCP服务器URI匹配
scope：必须包含工具所需的必要作用域
exp（过期时间）：必须在未来（Unix时间戳）
iss（发行人）：应与Casdoor的授权服务器URL匹配
sub（主题）：用户标识符
client_id：接收令牌的应用程序/客户端

# Alternative: Decode token with jq
echo "YOUR_JWT_TOKEN" | cut -d. -f2 | base64 -d | jq

令牌内省端点

Casdoor提供一个令牌 introspection 端点（RFC 7662），用于验证和检查令牌：

curl -X POST https://your-casdoor.com/api/login/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "token=ACCESS_TOKEN"

响应包含：

{
  "active": true,
  "scope": "read:application write:application",
  "client_id": "your-client-id",
  "username": "admin",
  "exp": 1735689600,
  "iat": 1735603200,
  "aud": "https://your-mcp-server.com"
}

使用 curl 进行测试

使用curl进行手动OAuth流程测试：

# 1. Test authorization endpoint (requires browser)
# Open in browser:
https://your-casdoor.com/login/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=http://localhost:8080/callback&
  response_type=code&
  scope=read:application&
  state=random-state

# 2. Exchange authorization code for token
curl -X POST https://your-casdoor.com/api/login/oauth/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost:8080/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# 3. Use access token with MCP server
curl https://your-mcp-server.com/api/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

调试日志记录

在您的MCP客户端或服务器中启用调试日志记录，以查看详细的OAuth流程：

适用于MCP客户端：

检查客户端配置，确认是否处于调试/详细模式
查看客户端日志，了解OAuth重定向、令牌交换和API调用情况
使用浏览器开发者工具或mitmproxy捕获网络流量

For MCP servers:适用于MCP服务器：

启用服务器调试日志，以查看传入请求
记录令牌验证结果（成功/失败及原因）
监控授权检查和作用域验证

网络调试

使用浏览器开发者工具或网络分析工具：

浏览器开发者工具（F12）：
- 网络选项卡显示所有OAuth重定向和API调用
- 控制台选项卡显示 JavaScript 错误
- 应用选项卡显示存储的令牌和Cookie

适用于 CLI 客户端的 mitmproxy：

mitmproxy -p 8080
# Configure client to use proxy: http://localhost:8080

Wireshark 用于低级数据包分析

另请参阅

授权与作用域 — 作用域参考
错误处理 — JSON-RPC 错误码
身份验证 — OAuth 和令牌
自定义作用域 — 代理应用程序作用域
动态客户端注册 — DCR 设置

常见错误​

401 未授权，来自MCP服务器​

浏览器中的CORS错误​

重定向URI不匹配​

发现端点404​

DCR 注册被拒绝​

同意屏幕未显示​

insufficient_scope 错误​

无效目标/资源错误​

Claude Desktop / 光标连接失败​

调试工具​

MCP检查器​

测试发现端点​

检查 JWT 令牌​

令牌内省端点​

使用 curl 进行测试​

调试日志记录​

网络调试​

另请参阅​

常见错误

401 未授权，来自MCP服务器

浏览器中的CORS错误

重定向URI不匹配

发现端点404

DCR 注册被拒绝

同意屏幕未显示

insufficient_scope 错误

无效目标/资源错误

Claude Desktop / 光标连接失败

调试工具

MCP检查器

测试发现端点

检查 JWT 令牌

令牌内省端点

使用 curl 进行测试

调试日志记录

网络调试

另请参阅