Accesso con OAuth

Un assistente IA accede a Setherion con OAuth invece che con una chiave API: la persona preme Allow su una pagina di Setherion, e l’assistente riceve un token. Questa pagina è il contratto per creare il tuo client. Se vuoi solo collegare Claude, ChatGPT, Cursor o VS Code, segui MCP: collegare un assistente IA.

Il flusso è OAuth 2.1 come lo richiede la specifica di autorizzazione MCP (2025-06-18):

• il flusso con codice di autorizzazione, con PKCE (S256) sempre obbligatorio;
• solo client pubblici, senza client secret;
• registrazione dinamica del client (RFC 7591), così nessuno incolla un client id da nessuna parte;
• token legati a una sola risorsa, l’endpoint MCP (RFC 8707).

I token funzionano sul Server MCP e da nessun’altra parte. Gli endpoint REST di questo riferimento richiedono una chiave API.

1. Scoperta

Invia una richiesta all’endpoint MCP senza alcuna credenziale. Il 401 indirizza ai metadati della risorsa (RFC 9728) nella sua intestazione WWW-Authenticate:

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

Lo stesso documento si trova su /.well-known/oauth-protected-resource. Poi leggi i metadati del server di autorizzazione (RFC 8414):

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

Entrambi i documenti, la registrazione e l’endpoint dei token rispondono a qualsiasi origine (Access-Control-Allow-Origin: *), quindi un client in una pagina del browser può chiamarli.

2. Registrazione

Registrati una volta per ogni installazione. La registrazione non concede nulla da sola: una persona deve comunque premere Allow, e il codice viene inviato solo agli indirizzi esatti registrati qui.

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

Un indirizzo di reindirizzamento deve essere https, oppure http verso questa stessa macchina (localhost, 127.0.0.1 o [::1]). Non può avere un frammento né un nome utente. L’unico indirizzo che non è https né http è cursor://anysphere.cursor-mcp/oauth/callback, per le vecchie app Cursor.

Qualunque metodo di autenticazione chieda un client, viene registrato come client pubblico senza segreto, e la risposta lo dice:

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Lo stato è 201. Le registrazioni sono limitate a 20 all’ora per indirizzo di rete.

3. Chiedi alla persona

Apri l’endpoint di autorizzazione nel browser della persona. È una pagina, non un’API: la persona accede a Setherion se non l’ha già fatto, vede il nome che hai registrato e dove verrà rimandata, e preme Allow o Cancel.

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

Il verifier deve avere da 43 a 128 caratteri tra A-Z a-z 0-9 - . _ ~; conservalo fino al passaggio 4.

La persona viene rimandata al tuo redirect_uri con:

• su Allow: code, state e iss (l’issuer);
• su Cancel: error=access_denied, error_description=The request was declined., state e iss;
• su un problema con la richiesta, una volta che client e indirizzo risultano autentici: error, error_description, state e iss. L’error è unsupported_response_type, invalid_request (PKCE mancante, o il metodo non è S256) oppure invalid_target (la risorsa non è l’endpoint MCP).

Se il client è sconosciuto, o l’indirizzo non è uno di quelli che ha registrato, la pagina lo dice alla persona e non manda nessuno da nessuna parte, quindi questa pagina non può mai essere usata per reindirizzare qualcuno a un indirizzo che non hai registrato.

4. Scambia il codice

Invia i campi codificati come form, come specifica OAuth. Viene accettato anche JSON con gli stessi nomi.

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

Invia l’access token al Server MCP come Authorization: Bearer sto_.... I token non vengono mai messi in cache: la risposta contiene Cache-Control: no-store.

5. Aggiornamento

Un access token dura un’ora. Prima che scada, o quando il server MCP risponde 401, scambia il refresh token:

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

La risposta è la stessa del passaggio 4, con un refresh token nuovo. Quello vecchio smette di funzionare, quindi salva ogni volta quello nuovo.

Errori

Ogni errore dell’endpoint dei token ha lo stato 400, tranne server_error, e il corpo { "error": "...", "error_description": "..." }.

Chiudere una connessione

La persona può scollegare un assistente in Settings, poi AI assistants and MCP. Ogni token di quella connessione, di accesso e di aggiornamento, smette di funzionare alla richiesta successiva, non quando scade l’ora. Elencare e chiudere le connessioni è possibile solo da una sessione Setherion con accesso effettuato, quindi nulla di ciò che un assistente possiede può farlo.

Usare invece una chiave API

Un client che può inviare solo un’intestazione fissa può saltare tutto questo e inviare una chiave API al server MCP. Vedi Autenticazione.