--- title: "Connecter un agent" description: "Comment connecter un agent IA à Notarium : un jeton d'accès personnel (PAT), un connecteur OAuth pour les clients web et le transport POST /mcp." --- # Connecter un agent Un agent dialogue avec Notarium par un unique endpoint — `POST /mcp`. C'est la [passerelle MCP](/docs/agents/intent-tools/) intégrée : le même moteur et les mêmes données que dans l'éditeur web, mais avec un jeu restreint d'outils d'intention au lieu d'un accès direct au stockage. Un agent se connecte de deux façons : avec un jeton d'accès personnel (PAT) pour les clients programmatiques, ou avec un connecteur OAuth pour les versions navigateur de claude.ai et chatgpt.com. ## Transport : POST /mcp L'endpoint `POST /mcp` implémente le transport streamable-HTTP du `@modelcontextprotocol/sdk` officiel. Il est **stateless** : chaque requête démarre un serveur neuf doté des permissions de votre jeton et renvoie une seule réponse JSON, et non un flux SSE. `GET` et `DELETE` renvoient `405` — ici, aucun flux n'est initié par le serveur. L'endpoint est compatible avec le connecteur MCP de l'API Claude, avec Claude Code et avec tout client MCP HTTP capable d'envoyer un jeton Bearer. ```bash curl -sS https://notarium.example.com/mcp \ -H "Authorization: Bearer ntp__" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Option 1. Jeton d'accès personnel (PAT) Le PAT est la voie principale pour les clients programmatiques (API Claude, Claude Code, clients MCP configurables). Le jeton se transmet dans l'en-tête `Authorization: Bearer `. Son format est `ntp__` : le préfixe `ntp_` le rend facile à repérer dans les journaux et les fuites, la partie id sert à une recherche rapide, et le secret n'est stocké en base que sous forme de hachage — il ne s'affiche qu'une seule fois, au moment de l'émission. Un jeton s'émet de deux manières : - **Dans l'interface** — la section des jetons dans les réglages. Vous y indiquez un nom, un niveau (`read` ou `write`) et, si vous le souhaitez, une portée limitée à certains espaces ainsi qu'une date d'expiration. - **Via l'API** — `POST /api/me/tokens`. La permission `self:manage` est requise : vous seul pouvez donc émettre un jeton, par le biais d'une session, et jamais l'agent lui-même (un jeton ayant fuité ne peut pas en émettre un nouveau). > [!important] Les permissions d'un jeton sont un plafond > Un jeton `read` ne **voit** même pas les outils d'écriture dans `tools/list` : ce ne sont pas des outils qui « apparaissent puis refusent », ils sont tout simplement absents de la liste. L'ensemble des espaces du jeton détermine les espaces auxquels l'agent peut accéder ; tout ce qui se trouve en dehors reste inatteignable par conception. Les permissions se modifient après l'émission (nom, niveau, ensemble d'espaces) sans recréer le secret — le changement prend effet dès l'appel suivant. ## Option 2. Connecteur OAuth pour les clients web Lorsqu'on ajoute un « custom connector », les interfaces web de **claude.ai** et de **chatgpt.com** n'acceptent qu'OAuth : aucun champ ne permet d'y coller un jeton Bearer. Notarium embarque donc une fine **façade OAuth 2.1** (Notarium est son propre Authorization Server — il n'y a personne à qui déléguer : une instance auto-hébergée détient les comptes). Comment ça marche : 1. Une requête vers `POST /mcp` sans jeton renvoie `401`, avec un en-tête `WWW-Authenticate` qui pointe vers les documents de découverte (RFC 9728 / RFC 8414). 2. Le client passe par `GET /oauth/authorize` : vous vous authentifiez avec votre session en cours, puis vous choisissez les espaces sur l'écran de consentement (sélection multiple, « All spaces » par défaut). 3. `POST /oauth/token` avec PKCE (méthode S256) émet un jeton d'accès (`nto_…`) et, si `offline_access` est demandé, un jeton de rafraîchissement (`ntr_…`). Le jeton émis pointe vers le même principal et est validé au même point de contrôle qu'un PAT ou qu'une session. Son niveau est `read` ou `write`, mais **jamais `manage`** : un jeton de connecteur ayant fuité ne peut ni émettre un nouveau jeton ni octroyer un accès. Les connexions se gèrent dans la section Connected apps, où vous pouvez changer leur niveau ou leur ensemble d'espaces sans repasser par le consentement. > [!note] Claude et ChatGPT se connectent via OAuth > Dans ChatGPT, Notarium s'ajoute comme un connecteur ordinaire par-dessus le même OAuth — exactement comme dans claude.ai : connexion avec votre session en cours, choix des espaces sur l'écran de consentement, et l'agent retrouve votre jeu habituel d'outils d'intention. ## Le mode none : sans jeton Si une instance démarre avec `AUTH_MODE=none` (desktop, dev, intranet de confiance — l'opérateur coupe délibérément l'authentification), la passerelle fonctionne sans authentification : `/mcp` se comporte comme un principal unique en accès total, et claude.ai/ChatGPT l'ajoutent d'emblée comme connecteur sans authentification. Dans ce mode, il n'y a pas de façade OAuth. > [!warning] Un serveur sans authentification est public > En mode `none`, quiconque connaît l'URL peut l'appeler. Ce n'est acceptable que pour un usage mono-utilisateur, une démo ou un réseau de confiance. Pour une instance multi-utilisateur, utilisez `AUTH_MODE=password` (la valeur par défaut). ## Ensuite - [Règles de l'agent](/docs/agents/agent-files/) — comment faire démarrer chaque session par `start_session` sans avoir à le redemander à chaque fois. - [Outils d'intention](/docs/agents/intent-tools/) — l'ensemble complet des 21 outils et l'ordre des appels. - [Sécurité et visibilité](/docs/agents/security/) — comment les permissions s'appliquent à chaque appel. - [Démarrage rapide : connecter un agent](/docs/getting-started/connect-agent/) — un exemple minimal de bout en bout.