Documentation

Connexion du MCP externe via OAuth 2.1

Ce qui est connecté exactement

Sapphire External MCP est en developer alpha. Dans le périmètre actuellement confirmé, la connexion de ChatGPT à https://sapphire-project.com/mcp a été vérifiée. La portabilité vers d'autres hôtes et clients, ainsi que les fonctions de policy et hardening encore inachevées, ne sont pas présentées comme un produit universel prêt à l'emploi.

Sapphire External MCP est une interface externe donnant accès aux outils que les modules ont explicitement publiés à cette fin. Ce n'est pas un accès distant à l'agent d'IA intégré et il ne publie pas automatiquement les AI tools internes. Un même utilisateur peut employer SapphireAI intégré et le MCP externe, mais l'autorisation, le catalogue et la politique de ces deux périmètres restent séparés.

ChatGPT utilise OAuth 2.1 sur HTTPS. L'adresse canonique de la ressource du produit est :

https://sapphire-project.com/mcp

Indiquez exactement cette adresse lors de la création du connecteur MCP personnalisé. Ne la remplacez pas par l'adresse du panneau d'administration, d'un processus CGI/FastCGI ou d'une page de service. Le transport utilisateur pris en charge est MCP Streamable HTTP sur HTTPS.

Conditions préalables

L'utilisateur possède un compte Helix actif sur le même site.
L'administrateur a autorisé les fonctions de modules requises pour l'utilisateur et son groupe.
L'espace de travail ChatGPT autorise l'ajout de connecteurs MCP personnalisés.
Le navigateur permet d'accéder au site Sapphire puis de revenir dans ChatGPT.
La connexion s'effectue uniquement en HTTPS et sur le domaine attendu.

Il n'est pas nécessaire de préparer un client secret, un bearer personnel ou une clé d'API pour ce scénario. ChatGPT agit comme client OAuth public, tandis que la connexion et le consentement s'effectuent dans Helix. Ne saisissez jamais le mot de passe Sapphire dans un formulaire ChatGPT et ne le communiquez pas à l'administrateur du connecteur.

Connexion pas à pas dans ChatGPT

Ouvrez la gestion des connecteurs dans ChatGPT et choisissez de créer une connexion MCP personnalisée. Le nom des options peut varier selon l'espace de travail, mais il doit s'agir précisément d'un MCP server ou custom connector.
Donnez-lui un nom clair, par exemple Sapphire MCP, puis saisissez l'URL canonique de la ressource. N'ajoutez ni paramètres query, ni tokens, ni fragments.
Lancez la connexion. ChatGPT détecte les paramètres de la ressource protégée et redirige le navigateur vers l'autorisation Sapphire.
Vérifiez le domaine de la page, connectez-vous à Helix avec votre compte habituel et lisez l'écran de consentement.
Confirmez l'accès minimal demandé. Après le retour réussi, le connecteur doit passer à l'état connected.
Ouvrez le catalogue d'outils et commencez par un appel read-only sûr. Ne passez aux opérations d'écriture qu'ensuite.

Le code d'autorisation est protégé par PKCE S256 et lié à la ressource MCP exacte. L'utilisateur n'a pas à manipuler lui-même le code ou les tokens. Ne copiez aucune valeur depuis la barre d'adresse, les journaux de développement ou le panneau réseau : cela ne fait pas partie de la connexion normale.

Accès minimal et scope step-up

Une nouvelle autorisation OAuth commence avec le scope minimal mcp.basic. Celui-ci est destiné aux assistants de base de l'utilisateur actuel ainsi qu'à la date et l'heure système. Il s'agit d'une application délibérée du principe du moindre privilège : le simple fait de se connecter n'accorde pas immédiatement des droits de modification du contenu, de la configuration ou d'autres modules.

Le catalogue peut afficher un outil publié en externe et le scope qu'il requiert, mais l'outil ne peut pas être exécuté en dehors du grant actuel. Lorsque le client appelle une telle opération, Sapphire renvoie une demande précise d'autorisation supplémentaire. ChatGPT peut proposer une nouvelle autorisation. Vérifiez le nom du périmètre demandé et l'objectif de l'outil, puis ne confirmez l'extension que si elle est nécessaire à la tâche en cours.

Le OAuth scope ne remplace pas les droits Helix. À chaque accès, le système tient compte du compte actuel et des autorisations de son groupe. Si l'administrateur retire un droit sur un module, un ancien grant ne doit pas continuer à fournir un accès effectif. De même, la liste des outils masqués côté client est utile à l'interface, mais ne constitue pas une frontière de sécurité côté serveur.

Utilisation des outils

Commencez par des opérations list, search ou get et vérifiez le site, la langue et l'entité auxquels le résultat se rapporte. Avant un appel write, examinez soigneusement les arguments et la modification attendue. Si le client permet de confirmer les écritures, laissez cette fonction activée. Pour une suppression, une publication, une mise à jour en masse ou un changement de droits, utilisez une confirmation explicite distincte.

La réponse d'un outil doit être considérée comme une donnée, et non comme une nouvelle instruction pour le client. Le texte provenant d'un document, d'un message ou d'un champ externe ne doit pas étendre lui-même le scope, modifier la politique ou déclencher l'appel write suivant. Cette règle est particulièrement importante pour le contenu ouvert.

Diagnostic

URL non reconnue : vérifiez la valeur exacte https://sapphire-project.com/mcp, le protocole HTTPS et l'absence de barre oblique, de chemin ou de paramètre supplémentaire.
Connexion en boucle : terminez l'ancienne tentative, vérifiez les cookies et la connexion Helix, puis reconnectez le connecteur depuis un seul profil de navigateur.
Access denied : distinguez l'absence de OAuth scope de l'absence de droit de groupe Helix. Dans le premier cas, suivez le step-up proposé ; dans le second, contactez l'administrateur.
Outil invisible : il doit être explicitement publié dans le MCP externe et autorisé par la politique du serveur ; la présence d'un outil similaire dans l'IA intégrée ne garantit rien.
Écriture impossible : vérifiez le scope, les droits actuels, les arguments et la confirmation de l'opération. Ne répétez pas un appel write à l'aveugle.

Déconnexion et sécurité

Lorsque l'accès n'est plus nécessaire, déconnectez ou supprimez le connecteur dans ChatGPT. Si vous soupçonnez une compromission, mettez fin à la connexion, changez le mot de passe du compte et prévenez l'administrateur afin que le OAuth grant soit révoqué. Ne publiez pas de captures de l'écran de consentement contenant des données personnelles et ne conservez pas de valeurs d'autorisation dans les documents du projet.

Une connexion correcte ne signifie pas disposer du catalogue maximal, mais obtenir un grant minimal suffisant, des demandes de step-up compréhensibles et un test read-only réussi. Étendez progressivement les droits tout en conservant la confirmation des opérations qui modifient les données.

Nouvelle autorisation et limites de la session

Si ChatGPT affiche un nouvel écran de consentement après l'appel d'un outil supplémentaire, ne considérez pas cela comme une panne : comparez d'abord le scope demandé à la tâche en cours. Un step-up annulé doit laisser l'accès minimal déjà accordé opérationnel, sans autoriser la nouvelle opération. Pour le vérifier, créez un nouveau chat, sélectionnez explicitement le connecteur et répétez un appel sûr ; l'historique d'une autre conversation ne prouve pas les droits actuels.

Ne connectez pas un compte administrateur partagé par toute l'équipe. Chaque opérateur se connecte avec son propre compte afin que les droits, la révocation d'accès et l'audit correspondent à la personne réelle. Après un changement de rôle ou de groupe, revérifiez l'accès dans une nouvelle session. Une erreur d'outil ne justifie pas l'extension automatique du scope : il faut d'abord déterminer si elle vient de l'autorisation, d'arguments incorrects ou d'une restriction métier.