NotariumDocumentation
Version de la documentation: latest
FR

Connecter un agent

Un agent dialogue avec Notarium par un unique endpoint — POST /mcp. C'est la passerelle MCP 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.

curl -sS https://notarium.example.com/mcp \
  -H "Authorization: Bearer ntp_<id>_<secret>" \
  -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 <pat>.

Son format est ntp_<id>_<secret> : 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).
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.

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.

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