Autentificare MCP

Endpoint-ul /mcp necesită un access_token Supabase transmis ca token Bearer. Majoritatea clienților MCP obțin aceasta automat prin fluxul OAuth 2.1 PKCE. De asemenea, poți furniza un token manual pentru testare.

Fluxul OAuth 2.1 PKCE

Flowstep implementează un server de autorizare OAuth 2.1 complet la https://api.flowstep.ai. Clienții MCP îl descoperă prin puncte finale de metadate RFC standard.

Lanțul de descoperire

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

Endpoint-uri OAuth

Metodă	Endpoint	Scop
`GET`	`/.well-known/oauth-protected-resource`	RFC 9728 resource metadata
`GET`	`/.well-known/oauth-authorization-server`	RFC 8414 server metadata
`POST`	`/oauth/register`	RFC 7591 dynamic client registration
`GET`	`/oauth/authorize`	Afișează formularul de autentificare
`POST`	`/oauth/authorize`	Procesează autentificare email/parolă
`GET/POST`	`/oauth/social-callback`	Google SSO callback
`POST`	`/oauth/token`	Schimb de cod și reîmprospătare de token

Metode de autentificare acceptate

Pagina de autorizare la /oauth/authorize acceptă:

Email/parolă — orice cont Flowstep cu o parolă setată
Google SSO — redirecționează prin autentificare socială Supabase, se întoarce la client automat

Crearea de conturi pentru utilizatorii conectării claude.ai

Pagina de autentificare OAuth nu include un formular de înregistrare. Dacă te conectezi prin conectorul personalizat claude.ai și nu ai încă un cont Flowstep, creează-l mai întâi la app.flowstep.ai, apoi revino la configurarea conectării pentru autentificare.

Mecanica tokenului

Proprietate	Valoare
Tip token	Supabase JWT (Bearer)
Expirare token de acces	~1 oră (reîmprospatată transparent de server)
Durata sesiunii MCP	30 de zile
Reîmprospătare token	Gestionat pe server — serverul reîmprospătează sesiunea subiacentă transparent; clienții MCP nu gestionează reîmprospatarea ei înșiși
Auth code TTL	5 minute (utilizare unică)
Pending social auth TTL	10 minute
Domenii	`openid`, `offline_access`

Tokenurile sunt validate la fiecare cerere prin supabase.auth.getUser(token). Un token expirat sau invalid returnează 401 cu un antet WWW-Authenticate, care declanșează fluxul de re-autentificare al clientului. Dacă nu este prezent niciun antet Authorization, middleware-ul revine la o sesiune Supabase bazată pe cookie. Aceasta funcționează atunci când accesezi /mcp direct dintr-un browser cu o sesiune Flowstep activă. Clienții MCP folosesc întotdeauna calea Bearer.

Token manual (testare)

Pentru a apela endpoint-ul direct fără un flux OAuth client:

Conectează-te la app.flowstep.ai în browserul tău
Deschide DevTools → Console, rulează:

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

Transmite tokenul ca antet:

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

Sesiunile MCP durează 30 de zile — serverul reîmprospătează tokenul subiacent transparent, deci clienții care utilizează fluxul OAuth nu trebuie să se re-autentifice în timpul utilizării normale. Un token extras manual ca cel de mai sus încă expiră după aproximativ o oră; este numai pentru testare rapidă.

​Fluxul OAuth 2.1 PKCE

​Lanțul de descoperire

​Endpoint-uri OAuth

​Metode de autentificare acceptate

​Crearea de conturi pentru utilizatorii conectării claude.ai

​Mecanica tokenului

​Fallback-ul cookie-ului

​Token manual (testare)

Fluxul OAuth 2.1 PKCE

Lanțul de descoperire

Endpoint-uri OAuth

Metode de autentificare acceptate

Crearea de conturi pentru utilizatorii conectării claude.ai

Mecanica tokenului

Fallback-ul cookie-ului

Token manual (testare)