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

​
发现端点

每个传输路径都有各自的文档:客户端只有在其调用的 URL 位于所公布 resource 路径之下时才会接受该 resource。401 质询指向客户端实际调用路径所对应的文档。自行拼接该 URL(而非跟随质询)的客户端可以在此找到它;两份文档同时提供,已发现源站范围文档的客户端不受影响。 /.well-known/oauth-protected-resource 目前公布公共资源作用域 mcp。Pro 授权码授权返回内部作用域值 mcp_pro。遗留 API-key 授权与 client_credentials 返回 mcp。

​
端点

​
POST /api/oauth/register

动态客户端注册。返回 client_id(公共客户端,无 secret)。 请求:
响应:
Redirect URI 允许列表:http://localhost:<port> / http://127.0.0.1:<port>(任意端口),或与 MCP 服务器 → Redirect URI 允许列表 中托管 MCP 客户端回调地址完全一致。任何其他条目都会使整个注册返回 400 invalid_redirect_uri。 每次注册最多 8 个 redirect_uris;超出返回 400 invalid_request。 速率限制: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(可选)
授权响应:重定向到 redirect_uri,携带 code、state(请求中提供时)与 iss。iss 为发起流程的主机 AS 元数据中的 issuer(RFC 9207);元数据公布 authorization_response_iss_parameter_supported: true。 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。三种授权类型在限流器未配置或抛错时均失败开放；此时响应带有 X-RateLimit-Mode: degraded（已列入 Access-Control-Expose-Headers），以便运营方与跨域客户端区分健康限流放行与降级放行。Redis 存储故障时令牌持久化仍失败关闭。 令牌 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。