MCP OAuth 故障排除

实现参考: 本页面描述的身份验证逻辑在 apps/backend/src/middleware/api-key-oauth.middleware.ts 中实现。

​

身份验证场景

​

1. API 密钥和 OAuth 都禁用

• 所有请求都无需身份验证即可通过
• 不需要身份验证头
• 适用于不需要身份验证的公共端点

{
  "message": "Public endpoint - no authentication required"
}

​

2. 仅 API 密钥（OAuth 禁用）

• 需要通过 X-API-Key 头或查询参数提供有效的 API 密钥
• 关键问题: 如果 API 密钥缺失或无效，某些 MCP 客户端（如 Inspector）可能会尝试 OAuth 流程
• 这可能导致无限刷新循环和 429 速率限制错误

curl -H "X-API-Key: mcp_1234567890abcdef" \
  https://your-domain.com/api/endpoint

{
  "error": "authentication_required",
  "error_description": "Authentication required via API key",
  "supported_methods": [
    "X-API-Key header",
    "query parameter (api_key or apikey)"
  ],
  "timestamp": "2024-01-01T00:00:00.000Z"
}

• 无限令牌刷新尝试
• 429 “请求过多” 错误
• Inspector 变得无法使用

​

3. API 密钥和 OAuth 都启用

• 接受 API 密钥和 OAuth 承载令牌
• 如果提供 API 密钥，则优先使用
• 如果没有提供 API 密钥，则回退到 OAuth
• 最灵活的配置

1. 未提供令牌: 启动 OAuth 流程
   Copy

   {
     "error": "authentication_required",
     "error_description": "Authentication required via OAuth bearer token or API key",
     "supported_methods": [
       "Authorization header (Bearer token)",
       "X-API-Key header",
       "query parameter (api_key or apikey)"
     ]
   }
   

2. 有效 API 密钥: 通过
   Copy

   curl -H "X-API-Key: mcp_1234567890abcdef" \
     https://your-domain.com/api/endpoint
   

3. 有效 OAuth 令牌: 通过
   Copy

   curl -H "Authorization: Bearer mcp_token_1234567890abcdef" \
     https://your-domain.com/api/endpoint
   

4. 无效凭据: 返回 401 并限制速率
   Copy

   {
     "error": "invalid_credentials",
     "error_description": "Authentication failed. Invalid credentials provided.",
     "timestamp": "2024-01-01T00:00:00.000Z"
   }
   

​

4. 仅 OAuth（API 密钥禁用）

• 需要 OAuth 承载令牌
• 不支持 API 密钥
• 纯 OAuth 身份验证

curl -H "Authorization: Bearer mcp_token_1234567890abcdef" \
  https://your-domain.com/api/endpoint

{
  "error": "authentication_required",
  "error_description": "Authentication required via OAuth bearer token",
  "supported_methods": ["Authorization header (Bearer token)"],
  "WWW-Authenticate": "Bearer realm=\"MetaMCP\", scope=\"admin\""
}

{
  "error": "invalid_token",
  "error_description": "The provided OAuth token is invalid or has expired.",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

​

常见问题和解决方案

​

问题 1: 无限 OAuth 刷新循环

• MCP Inspector 持续刷新令牌
• 429 “请求过多” 错误
• Inspector 变得无响应

1. 在端点配置中启用 OAuth:
   Copy

   {
     "enable_api_key_auth": true,
     "enable_oauth": true
   }
   

2. 配置 MCP 客户端仅使用 API 密钥:
   • 更新客户端配置以使用 X-API-Key 头
   • 在客户端设置中禁用 OAuth 流程
3. 使用仅 OAuth 配置:
   Copy

   {
     "enable_api_key_auth": false,
     "enable_oauth": true
   }
   

​

问题 2: 429 速率限制错误

• “身份验证尝试失败次数过多” 错误
• 因身份验证尝试而临时锁定

1. 等待速率限制重置（1 分钟）
2. 如果您启用了身份验证，请确保永远不要传入错误的 API 密钥。

​

问题 3: 访问被拒绝（403）错误

• 即使凭据有效也出现”访问被拒绝”错误
• “公共 API 密钥无法访问私有端点”消息

1. 对于私有端点: 使用端点创建者拥有的 API 密钥
2. 对于公共端点: 任何有效的 API 密钥或 OAuth 令牌都可以工作
3. 检查端点所有权:
   Copy

   # 获取端点详情
   curl -H "Authorization: Bearer your-token" \
     https://your-domain.com/api/endpoints/endpoint-uuid
   

​

问题 4: 错误的身份验证方法

• 使用 OAuth 时出现”需要通过 API 密钥进行身份验证”
• 使用 API 密钥时出现”需要通过 OAuth 承载令牌进行身份验证”

1. 检查端点配置:
   Copy

   # 获取端点配置
   curl -H "Authorization: Bearer your-token" \
     https://your-domain.com/api/endpoints/endpoint-uuid
   

2. 使用正确的身份验证方法:
   • API 密钥: X-API-Key 头或 api_key 查询参数
   • OAuth: Authorization: Bearer 头