Skip to main content
WorldMonitor 运行一个最小化的 OAuth 2.1 授权服务器,目前其面向客户端的唯一用途是授予对 /api/mcp MCP 服务器的访问权限。它实现了:

​
发现端点

/.well-known/oauth-protected-resource 目前公布公共资源作用域 mcp。Pro 授权码授权返回内部作用域值 mcp_pro。遗留 API-key 授权与 client_credentials 返回 mcp。

​
端点

​
POST /api/oauth/register

动态客户端注册。返回 client_id(公共客户端,无 secret)。 请求:
响应:
Redirect URI 允许列表:仅接受以下前缀:
  • https://claude.ai/api/mcp/auth_callback
  • https://claude.com/api/mcp/auth_callback
  • http://localhost:<port> / http://127.0.0.1:<port> — 任意端口
速率限制:5 次注册 / 60 秒 / IP。 客户端 TTL:90 天滑动窗口(每次成功的令牌交换都会刷新)。

​
GET /api/oauth/authorize

启动 OAuth 流程。它会渲染同意页并重定向到 Clerk 登录，随后签发与调用方账户绑定的授权码。该流程的 Pro 登录分支由相邻的 GET /oauth/authorize-pro 提供（客户端不会直接调用）：Pro 订阅者与已确认的免费账户均可完成授权；服务方确认付费覆盖期已经结束时，账户会转入同一受限免费账户路径，保留 OAuth 身份并仅能使用按免费额度计量的 free-account 工具。无法校验的状态返回可重试的 503；不具备免费账户资格的非免费权益不足或已停用权益仍会被拒绝。 必填 query 参数:
  • response_type=code
  • client_id — 来自 DCR
  • redirect_uri — 必须与已注册的相匹配
  • code_challenge — PKCE S256
  • code_challenge_method=S256
  • state — 不透明值
  • scope(可选)
Code TTL:10 分钟。一次性使用(交换时原子 GETDEL)。

​
POST /api/oauth/token

用授权码换取访问令牌,或刷新已有令牌。 Grant type: authorization_code:
响应:
Grant type: refresh_token:
速率限制:10 次令牌请求 / 分钟。限制器按键依据为:client_credentials 按 client_secret 哈希,有 client_id 时(authorization_code 与 refresh_token)按 client_id,两者均不可用时才回退到调用方 IP。 令牌 TTL:
  • Access token:1 小时
  • Refresh token:7 天
Access 与 refresh 令牌为不透明 UUID。所有令牌端点响应均包含 Cache-Control: no-store, Pragma: no-cache。

​
使用令牌

在每次 MCP 请求中携带访问令牌:
令牌绑定到用户账户，并在每次调用时重新校验权益。套餐降级会在下一次请求时移除不再具备的付费能力，但不会无条件撤销 OAuth 身份：服务方确认付费覆盖期已经结束时，令牌继续作为受限、按额度计量的免费账户凭据，只能调用 free-account 工具；不具备免费账户资格的非免费权益不足或已停用权益仍会被拒绝。

​
错误响应

依据 RFC 6749 §5.2:
常见错误:invalid_request、invalid_client、invalid_grant、unsupported_grant_type、invalid_scope。