Authentification et permissions MCP

Chaque requête vers POST /mcp exige un access token OAuth émis pour l’audience exacte de la ressource MCP. Chataigne vérifie le token, la session utilisateur active, le client OAuth, le consentement et les scopes à chaque requête.

Autorisation effective

Un outil métier est autorisé par l’intersection de trois contrôles :

scopes OAuth consentis
  ∩ permissions actuelles du rôle
  ∩ membership actuel de la ressource cible

Le serveur résout en base de données la véritable organisation propriétaire de la cible. Un appelant ne peut pas autoriser un article de catalogue, une commande ou une conversation en fournissant l’identifiant d’un autre établissement.

Appelant	Règle multi-tenant	Règle de scope
Utilisateur restaurant	Exige un membership actuel dans l’établissement ou son organisation parente et la permission de rôle	Toujours exigé
Administrateur global Chataigne	Peut cibler toute organisation ou établissement sans membership	Toujours exigé
Utilisateur révoqué ou banni	Refusé à la requête suivante	Non applicable
Client OAuth désactivé ou consentement révoqué	Refusé à la requête suivante	Non applicable

L’accès administrateur global est large mais jamais implicite. Le token doit contenir le scope de lecture ou d’écriture requis. N’accordez les scopes d’écriture en production qu’aux clients de confiance.

Scopes

Les scopes d’identité sont openid, profile et offline_access. Les scopes métier suivent le format ressource.action.

Domaine	Scopes de lecture	Scopes d’écriture
Espaces de travail	`businessOrganization.read`, `location.read`	—
Paramètres établissement	`storeSettings.read`, `orderSettings.read`, `openingHoursSettings.read`, `deliverySettings.read`, `paymentMethodSettings.read`, `settings.read`	—
Statut des commandes	`locationStatusSettings.read`	`locationStatusSettings.write`
Catalogue	`catalog.read`	`catalog.updateAvailability`
Commandes	`orders.read`	`orders.write`
Clients	`customers.read`	—
Conversations	`conversations.read`	`conversations.write`
Analytics	`analytics.read`	—
Remises	`discounts.read`	—
Intégrations	`integrations.read`	—
Autres paramètres	`ai.read`, `loyalty.read`, `referrals.read`, `notifications.read`	—

Les outils dont le scope statique est absent n’apparaissent pas dans tools/list. Appeler directement un outil masqué ne contourne pas ce contrôle. chataigne_location_settings_get vérifie aussi le scope granulaire de chaque section demandée et refuse l’appel entier si une section n’est pas autorisée. Les scopes d’administration de plateforme et leurs contrôles supplémentaires de rôle en temps réel sont documentés uniquement dans l’espace Admin protégé.

Cycle de vie du token

Les access tokens sont liés à l’audience de l’URL MCP canonique.
Authorization Code utilise PKCE.
Les refresh tokens tournent.
Une session Better Auth actuelle, un utilisateur actif, un client OAuth activé et un consentement correspondant sont exigés.
Les memberships et permissions de rôle sont lus en temps réel : une suppression d’accès prend effet à la requête MCP suivante.

Scopes recommandés

Pour un assistant limité aux questions opérationnelles, commencez avec :

openid profile offline_access
location.read catalog.read orders.read
customers.read conversations.read analytics.read

Ajoutez chaque scope d’écriture uniquement si le client est fiable et l’action opérationnelle nécessaire. Les outils d’écriture peuvent aussi être désactivés globalement, indépendamment du consentement OAuth.

Échecs d’authentification

Les échecs d’authentification renvoient HTTP 401 avec un header WWW-Authenticate vers les métadonnées de la ressource protégée. Les refus de permission d’un outil renvoient une erreur MCP sûre MCP_RESOURCE_FORBIDDEN sans révéler si un identifiant appartenant à un autre tenant existe.

​Autorisation effective

​Scopes

​Cycle de vie du token

​Scopes recommandés

​Échecs d’authentification

Autorisation effective

Scopes

Cycle de vie du token

Scopes recommandés

Échecs d’authentification