Connexion avec OAuth

Un assistant d’IA se connecte à Setherion avec OAuth plutôt qu’avec une clé d’API : la personne appuie sur Allow sur une page Setherion, et l’assistant reçoit un jeton. Cette page est le contrat à suivre pour créer votre propre client. Si vous voulez seulement connecter Claude, ChatGPT, Cursor ou VS Code, suivez MCP : connecter un assistant d’IA.

Le flux est OAuth 2.1, tel que le demande la spécification d’autorisation MCP (2025-06-18) :

• le flux avec code d’autorisation, avec PKCE (S256) toujours exigé ;
• clients publics uniquement, sans secret client ;
• l’enregistrement dynamique des clients (RFC 7591), pour que personne n’ait à coller un identifiant de client quelque part ;
• des jetons liés à une seule ressource, le point d’accès MCP (RFC 8707).

Les jetons fonctionnent sur le Serveur MCP et nulle part ailleurs. Les points d’accès REST de cette référence demandent une clé d’API.

1. Découvrir

Envoyez une requête au point d’accès MCP sans aucun identifiant. Le 401 renvoie vers les métadonnées de la ressource (RFC 9728) dans son en-tête 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"
}

Le même document se trouve à l’adresse /.well-known/oauth-protected-resource. Lisez ensuite les métadonnées du serveur d’autorisation (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"]
}

Les deux documents, l’enregistrement et le point d’accès des jetons répondent à n’importe quelle origine (Access-Control-Allow-Origin: *), de sorte qu’un client dans une page de navigateur peut les appeler.

2. Enregistrer

Enregistrez-vous une fois par installation. L’enregistrement n’accorde rien par lui-même : une personne doit encore appuyer sur Allow, et le code n’est renvoyé qu’aux adresses exactes enregistrées ici.

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

Une adresse de redirection doit être en https, ou en http vers cette machine (localhost, 127.0.0.1 ou [::1]). Elle ne peut contenir ni fragment ni nom d’utilisateur. La seule adresse qui n’est ni en https ni en http est cursor://anysphere.cursor-mcp/oauth/callback, pour les anciennes applications Cursor.

Quelle que soit la méthode d’authentification demandée par un client, il est enregistré comme client public sans secret, et la réponse le dit :

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

Le statut est 201. Les enregistrements sont limités à 20 par heure et par adresse réseau.

3. Demander à la personne

Ouvrez le point d’accès d’autorisation dans le navigateur de la personne. C’est une page, pas une API : la personne se connecte à Setherion si elle ne l’est pas déjà, voit le nom que vous avez enregistré et l’endroit où elle sera renvoyée, puis appuie sur Allow ou 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

Donnez au vérificateur de 43 à 128 caractères parmi A-Z a-z 0-9 - . _ ~, et gardez-le jusqu’à l’étape 4.

La personne est renvoyée vers votre redirect_uri avec :

• si elle appuie sur Allow : code, state et iss (l’émetteur) ;
• si elle appuie sur Cancel : error=access_denied, error_description=The request was declined., state et iss ;
• en cas de problème avec la requête, une fois que le client et l’adresse sont reconnus comme authentiques : error, error_description, state et iss. L’error est unsupported_response_type, invalid_request (PKCE absent, ou méthode autre que S256) ou invalid_target (la ressource n’est pas le point d’accès MCP).

Si le client est inconnu, ou si l’adresse n’en fait pas partie, la page le dit à la personne et n’envoie personne nulle part, de sorte que cette page ne peut jamais servir à rediriger quelqu’un vers une adresse que vous n’avez pas enregistrée.

4. Échanger le code

Envoyez des champs encodés en formulaire, comme OAuth le prévoit. Du JSON avec les mêmes noms est accepté aussi.

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

Envoyez le jeton d’accès au Serveur MCP sous la forme Authorization: Bearer sto_.... Les jetons ne sont jamais mis en cache : la réponse porte Cache-Control: no-store.

5. Rafraîchir

Un jeton d’accès dure une heure. Avant qu’il n’expire, ou lorsque le serveur MCP répond 401, échangez le jeton de rafraîchissement :

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 réponse est la même qu’à l’étape 4, avec un nouveau jeton de rafraîchissement. L’ancien cesse de fonctionner, donc enregistrez le nouveau à chaque fois.

Erreurs

Chaque erreur du point d’accès des jetons a le statut 400, à l’exception de server_error, et le corps { "error": "...", "error_description": "..." }.

Mettre fin à une connexion

La personne peut déconnecter un assistant dans Settings, puis AI assistants and MCP. Chaque jeton de cette connexion, d’accès comme de rafraîchissement, cesse de fonctionner dès sa toute prochaine requête, et non à la fin de l’heure. Lister et terminer les connexions n’est possible que depuis une session Setherion connectée, donc rien de ce que détient un assistant ne peut le faire.

Utiliser une clé d’API à la place

Un client qui ne peut envoyer qu’un en-tête fixe peut se passer de tout cela et envoyer une clé d’API au serveur MCP. Voir Authentification.