跳转到主要内容
/mcp 端点需要将 Supabase access_token 作为 Bearer 令牌传递。大多数 MCP 客户端通过 OAuth 2.1 PKCE 流程自动获取。您也可以手动提供令牌用于测试。

​
OAuth 2.1 PKCE 流程

Flowstep 在 https://api.flowstep.ai 实现了完整的 OAuth 2.1 授权服务器。MCP 客户端通过标准 RFC 元数据端点发现它。

​
发现链

Client                       Flowstep API
  │
  ├─ 1. POST /mcp (no token) ──────────────────────────► 401
  │        WWW-Authenticate: Bearer resource_metadata=
  │        "https://api.flowstep.ai/.well-known/oauth-protected-resource"
  │
  ├─ 2. GET /.well-known/oauth-protected-resource ──────► { authorization_servers: ["https://api.flowstep.ai"] }
  │
  ├─ 3. GET /.well-known/oauth-authorization-server ────► { authorization_endpoint, token_endpoint, ... }
  │
  ├─ 4. Client generates PKCE pair (code_verifier + code_challenge S256)
  │     Opens browser → https://api.flowstep.ai/oauth/authorize
  │     User logs in (email/password or Google SSO)
  │
  ├─ 5. Server redirects → http://127.0.0.1:<port>?code=AUTH_CODE
  │     (client's temporary local HTTP server captures this)
  │
  ├─ 6. Client sends code + code_verifier → POST /oauth/token
  │     ◄──────────────────────────────────────── { access_token, refresh_token }
  │
  └─ 7. Client sends Authorization: Bearer <access_token> on all /mcp requests

​
OAuth 端点

方法端点用途
GET/.well-known/oauth-protected-resourceRFC 9728 资源元数据
GET/.well-known/oauth-authorization-serverRFC 8414 服务器元数据
POST/oauth/registerRFC 7591 动态客户端注册
GET/oauth/authorize显示登录表单
POST/oauth/authorize处理电子邮件/密码登录
GET/POST/oauth/social-callbackGoogle SSO 回调
POST/oauth/token代码交换和令牌刷新

​
支持的登录方法

/oauth/authorize 处的授权页面支持：
  • 电子邮件/密码 — 任何设置了密码的 Flowstep 账户
  • Google SSO — 通过 Supabase 社交认证重定向，自动返回到客户端

​
claude.ai 连接器用户的账户创建

OAuth 登录页面不包含注册表单。如果您通过 claude.ai 的自定义连接器连接且还没有 Flowstep 账户，请先在 app.flowstep.ai 创建一个账户，然后返回连接器设置进行身份验证。

​
令牌机制

属性值
令牌类型Supabase JWT (Bearer)
访问令牌过期约 1 小时（由服务器透明刷新）
MCP 会话生命周期30 天
令牌刷新由服务器处理 — 服务器透明地刷新底层会话；MCP 客户端不会自己管理刷新
认证代码 TTL5 分钟（一次性使用）
待处理社交认证 TTL10 分钟
作用域openid, offline_access
令牌在每个请求上通过 supabase.auth.getUser(token) 验证。过期或无效的令牌返回 401 及 WWW-Authenticate 标头，触发客户端的重新身份验证流程。 如果不存在 Authorization 标头，中间件会回退到基于 cookie 的 Supabase 会话。这在从具有活跃 Flowstep 会话的浏览器直接访问 /mcp 时有效。MCP 客户端始终使用 Bearer 路径。

​
手动令牌（测试）

要在没有客户端 OAuth 流程的情况下直接调用端点：
  1. 在浏览器中登录 app.flowstep.ai
  2. 打开 DevTools → Console，运行：
const pairs = document.cookie.split("; ").map((c) => {
  const i = c.indexOf("=");
  return [c.slice(0, i), c.slice(i + 1)];
});
const authPairs = pairs
  .filter(([k]) => /^sb-.+-auth-token(\.\d+)?$/.test(k))
  .sort(([a], [b]) => a.localeCompare(b));
const raw = authPairs.map(([, v]) => decodeURIComponent(v)).join("");
const session = JSON.parse(
  raw.startsWith("base64-") ? atob(raw.slice(7)) : raw,
);
console.log(session.access_token);
  1. 将令牌作为标头传递：
curl -X POST https://api.flowstep.ai/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
MCP 会话持续 30 天 — 服务器透明地刷新底层令牌，因此使用 OAuth 流程的客户端在正常使用中不需要重新身份验证。像上面那样手动提取的令牌仍在约 1 小时后过期；它仅用于快速测试。