Authentification et accès
Le serveur suit la spécification d'autorisation du protocole MCP : OAuth 2.1 avec le serveur d'autorisation d'Oxygenius (Auth0), découvert à partir de la ressource protégée. Chaque appel porte le jeton de l'utilisateur ; la société et les droits en sont déduits à chaque requête.
Déroulement
- Le client appelle
https://mcp.oxygenius.be/mcpsans jeton : le serveur répond 401 avec l'adresse de ses métadonnées. - Le client lit les métadonnées de ressource protégée (RFC 9728) : elles désignent le serveur d'autorisation d'Oxygenius.
- Le client lit les métadonnées du serveur d'autorisation et lance le flux code d'autorisation + PKCE, avec
resource=https://mcp.oxygenius.be/mcp(RFC 8707). - L'utilisateur se connecte avec son compte Oxygenius et autorise l'accès ; le client reçoit un jeton d'accès (et un jeton de rafraîchissement).
- Le client appelle le serveur avec
Authorization: Bearer …. Le serveur valide le jeton, résout l'utilisateur et sa société, puis filtre les outils selon ses permissions.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp"Découverte
| Document | Adresse |
|---|---|
| Métadonnées de la ressource protégée | https://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp |
| Serveur d'autorisation | Celui indiqué par authorization_servers ; ses métadonnées sont publiées à l'emplacement standard (/.well-known/openid-configuration). |
Exemple de métadonnées (le domaine du serveur d'autorisation est donné par le document réel) :
{
"resource": "https://mcp.oxygenius.be/mcp",
"authorization_servers": [
"https://<tenant>.auth0.com/"
],
"scopes_supported": [],
"resource_name": "Oxygenius"
}Clients OAuth
- Clients pré-enregistrés : le serveur n'utilise pas l'enregistrement dynamique de client (DCR). Claude utilise le client d'Oxygenius enregistré pour le connecteur ; un autre client demande son identifiant au support.
- URL de retour de Claude :
https://claude.ai/api/mcp/auth_callbackethttps://claude.com/api/mcp/auth_callback. - Flux : code d'autorisation avec PKCE et jeton de rafraîchissement (l'utilisateur reste connecté sans se réauthentifier à chaque session).
- Scopes : aucun scope particulier n'est exigé ; l'accès est réglé par les permissions de l'utilisateur dans Oxygenius.
Jetons
- Jetons JWT signés (RS256) par le serveur d'autorisation d'Oxygenius ; émetteur, signature et expiration vérifiés à chaque requête.
- Audience dédiée : l'audience du jeton doit être exactement l'URL du serveur MCP. Un jeton de l'application web d'Oxygenius est refusé par le serveur MCP, et un jeton délivré à un assistant n'ouvre pas l'API de l'application.
- Durée de vie courte ; le client le renouvelle avec son jeton de rafraîchissement.
- Le serveur ne journalise jamais un jeton. Pour écrire, il appelle l'API d'Oxygenius au nom de l'utilisateur avec un jeton d'API distinct et de courte durée, obtenu auprès du serveur d'autorisation d'Oxygenius par échange de jeton, ou signé par le serveur MCP lui-même ; ce jeton n'est jamais renvoyé au client MCP et n'ouvre que les opérations de l'API prévues pour le serveur MCP.
POST /mcp HTTP/1.1
Host: mcp.oxygenius.be
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream
{"jsonrpc":"2.0","id":1,"method":"tools/list"}Utilisateur et société
L'identifiant de l'utilisateur contenu dans le jeton est rapproché, à chaque requête, de son compte Oxygenius, puis de sa société. Aucun outil n'accepte de société, de base de données ou d'identifiant d'utilisateur en paramètre. Le serveur refuse (403) :
- un utilisateur inconnu ou désactivé dans Oxygenius ;
- un utilisateur rattaché à plusieurs sociétés, ou un identifiant partagé par plusieurs comptes ;
- une société inactive, ou qui n'a pas activé le connecteur (Paramètres → Intégration IA).
Le refus intervient avant tout message MCP : un utilisateur refusé ne voit même pas la liste des outils.
Permissions par outil
Chaque outil exige la même permission que l'écran correspondant de l'application Oxygenius ; ce sont des permissions, jamais des rôles. Un outil dont la règle n'est pas satisfaite n'apparaît pas dans tools/list et son appel est refusé. Dans un détail, les documents liés (factures d'un devis, devis d'un événement…) n'apparaissent qu'avec leur propre permission.
- Outils d'écriture : en plus de la permission, la société doit avoir activé Autoriser les outils d'écriture.
- Module Stock :
get_item_stockexige aussi le module de licence Stock. - Sans permission :
get_my_profile, qui ne renvoie que les données de l'utilisateur lui-même. - Visibilité fine : événements privés d'autrui masqués, courriels limités aux boîtes partagées avec l'utilisateur quand la société l'exige, types de document limités par rôle, prix d'achat réservés à la permission
profitability.data.view.
Permission Oxygenius exigée par chaque outil. L'une des permissions d'un outil suffit ; une permission marquée « en plus » est exigée en plus de celle-ci.
Réponses HTTP de refus
| Code | Cause | Que faire |
|---|---|---|
401 | Jeton absent, expiré, ou d'une autre audience. | Le client renouvelle le jeton ou relance la connexion. |
403 | Utilisateur ou société refusés (voir ci-dessus). | Vérifier l'activation du connecteur et le compte. Voir Dépannage. |
413 | Requête de plus de 64 Ko. | Les messages MCP sont petits : réduire la requête. |
429 | Plus de 60 requêtes par minute pour l'utilisateur. | Patienter une minute. |
Un refus propre à un outil (permission, document non modifiable, paramètre invalide…) n'est pas une erreur HTTP : l'outil renvoie un résultat isError: true avec un message explicite. Voir Référence technique.