Autenticació d'MCP

L’endpoint /mcp requereix un access_token de Supabase passat com a token de Bearer. La majoria de clients MCP l’obtenen automàticament a través del flux OAuth 2.1 PKCE. Podeu proporcionar un token manualment per a proves.

Flux OAuth 2.1 PKCE

Flowstep implementa un servidor d’autorització OAuth 2.1 complet a https://api.flowstep.ai. Els clients MCP el descobreixen a través d’endpoints de metadades RFC estàndards.

Cadena de descobriment

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

Endpoints OAuth

Mètode	Endpoint	Propòsit
`GET`	`/.well-known/oauth-protected-resource`	Metadades de recursos RFC 9728
`GET`	`/.well-known/oauth-authorization-server`	Metadades del servidor RFC 8414
`POST`	`/oauth/register`	Registre dinàmic de client RFC 7591
`GET`	`/oauth/authorize`	Mostra el formulari de connexió
`POST`	`/oauth/authorize`	Processa la connexió amb email/contrasenya
`GET/POST`	`/oauth/social-callback`	Devolució de crida Google SSO
`POST`	`/oauth/token`	Intercanvi de codi i actualització de token

Mètodes de connexió suportats

La pàgina d’autorització a /oauth/authorize permet:

Email/password — qualsevol compte Flowstep amb una contrasenya establerta
Google SSO — redirigeix a través de l’autenticació social de Supabase, torna al client automàticament

Creació de compte per a usuaris del connector de claude.ai

La pàgina de connexió OAuth no inclou un formulari de registre. Si us connecteu a través del connector personalitzat de claude.ai i no teniu encara un compte Flowstep, creeu-ne un primer a app.flowstep.ai, després torneu a la configuració del connector per autenticar-vos.

Mecànica de tokens

Propietat	Valor
Tipus de token	Supabase JWT (Bearer)
Venciment del token d’accés	~1 hora (actualitzat transparentment pel servidor)
Durada de la sessió MCP	30 dies
Actualització del token	Gestionar per la banda del servidor — el servidor actualitza la sessió subjacent transparentment; els clients MCP no gestionen l’actualització per si mateixos
TTL del codi d’autenticació	5 minuts (ús únic)
TTL d’autenticació social pendent	10 minuts
Abast	`openid`, `offline_access`

Els tokens es validen en cada sol·licitud a través de supabase.auth.getUser(token). Un token vençut o invàlid retorna 401 amb una capçalera WWW-Authenticate, que activa el flux de re-autenticació del client. Si no hi ha una capçalera Authorization, el middleware torna a una sessió Supabase basada en cookies. Això funciona quan accediu a /mcp directament des d’un navegador amb una sessió Flowstep activa. Els clients MCP sempre utilitzen la ruta de Bearer.

Token manual (proves)

Per cridar l’endpoint directament sense un flux OAuth del client:

Inicieu sessió a app.flowstep.ai al vostre navegador
Obriu DevTools → Console, executeu:

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);

Passeu el token com a capçalera:

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"}'

Les sessions MCP duren 30 dies — el servidor actualitza el token subjacent transparentment, de manera que els clients que utilitzen el flux OAuth no necessiten re-autenticar-se durant l’ús normal. Un token extret manualment com el de dalt segueix vencent al cap d’aproximadament una hora; és només per a proves ràpides.

​Flux OAuth 2.1 PKCE

​Cadena de descobriment

​Endpoints OAuth

​Mètodes de connexió suportats

​Creació de compte per a usuaris del connector de claude.ai

​Mecànica de tokens

​Retorn a cookie

​Token manual (proves)

Flux OAuth 2.1 PKCE

Cadena de descobriment

Endpoints OAuth

Mètodes de connexió suportats

Creació de compte per a usuaris del connector de claude.ai

Mecànica de tokens

Retorn a cookie

Token manual (proves)