NotariumDocumentation
Version de la documentation: latest
FR

Connecter un agent

Au cœur de Notarium : une seule et même base de connaissances, également ouverte à un humain et à un agent IA. Vous travaillez via l'éditeur web, l'agent via le point d'accès MCP intégré, et ses modifications sont versionnées, encadrées par les droits d'accès et signées d'une provenance, exactement comme les vôtres. Nul besoin de déployer un service séparé pour cela : la passerelle MCP vit dans le même processus et sur le même port que l'interface web.

Cette page est la voie rapide : émettre un jeton, indiquer le point d'accès et vérifier que l'agent voit bien votre base de connaissances. Le contrat complet (outils, conventions d'appel, mémoire, audit, sécurité) se trouve dans la section Agents et MCP.

Étape 1. Émettre un jeton

L'agent s'authentifie avec un jeton d'accès personnel (PAT). Émettez-en un dans les paramètres de votre compte (la section des jetons) — c'est là que se définissent aussi :

  • la portée — read ou write (le plafond de permissions du jeton) ;
  • une restriction par espace optionnelle — quels espaces sont accessibles ;
  • une durée de vie optionnelle.

Le jeton a la forme ntp_<id>_<secret> et n'est affiché qu'une seule fois — copiez-le immédiatement. Un PAT qui fuite ne permet aucune escalade : les actions de gestion (émettre des jetons, gérer l'appartenance, créer des espaces) ne sont accessibles que dans une session humaine, jamais via un jeton.

Les droits du jeton sont le plafond de l'agent

Un jeton en lecture seule ne voit tout simplement pas les outils d'écriture : ils n'apparaissent jamais dans son jeu d'outils. L'espace d'un autre utilisateur, lui, reste inaccessible, un point c'est tout. Accordez à l'agent exactement les droits qu'exige la tâche.

Étape 2. Indiquer le point d'accès

Configurez l'agent (ou le client MCP) pour utiliser ce point d'accès :

POST http://localhost:3000/mcp
Authorization: Bearer ntp_<id>_<secret>

Le transport est le streamable-HTTP du SDK MCP officiel, sans état, avec une seule réponse JSON par requête (GET et DELETE renvoient 405). Le point d'accès est compatible avec le connecteur MCP de l'API Claude et avec n'importe quel client MCP HTTP.

Les connecteurs web de claude.ai et chatgpt.com

Impossible de coller un PAT dans les connecteurs personnalisés des interfaces web : ils ne fonctionnent qu'en OAuth. Notarium embarque une fine façade OAuth — le connecteur s'authentifie avec votre session et reçoit un jeton rattaché au même principal. Les détails sont dans la section Connecter un agent.

Étape 3. Premier appel — start_session

Dans une nouvelle session, l'agent appelle start_session en premier. En une seule requête, il obtient votre profil, la liste des projets accessibles et le delta des changements depuis sa dernière visite — et, si vous passez une indication project, un index compact de ce projet également. C'est le contexte par lequel commencer le travail.

Vient ensuite la routine habituelle : explorer la structure (list_notes, recent_activity), chercher avant d'écrire (search — déduplication), puis écrire (create_note, edit_note, la mémoire via remember_about_user / remember_about_project). L'agent passe par un jeu restreint d'outils taillés pour des tâches précises, et non par des opérations universelles de lecture/écriture — chaque outil impose un comportement sûr (classe de la note, visibilité, provenance, vérification de version à l'enregistrement pour ne pas écraser les modifications d'autrui).

N'exposez pas une instance none au réseau

En mode AUTH_MODE=none, le point d'accès /mcp est ouvert sans jeton (un unique principal en accès total). C'est pratique pour un poste de travail ou un environnement de confiance, mais une telle instance ne doit jamais être exposée à un réseau public.

Étape 4. L'inscrire dans les règles de l'agent

Quel outil appeler, c'est le modèle qui en décide : mieux vaut donc écrire une bonne fois pour toutes « appeler start_session en premier » dans les instructions permanentes de l'agent (CLAUDE.md, AGENTS.md, règles Cursor, prompt système) — avec le handle de votre projet :

- Au début d'une nouvelle session, appelle `start_session(project: "acme/website")`
  sur le serveur MCP `notarium`.
- Avant toute écriture, commence par `search(...)` — ne crée pas de doublons.

Sinon, vous finirez par orienter l'agent vers votre base de connaissances à la main, à chaque fois. La version détaillée — avec la carte de votre canon et la séparation entre règles globales et règles par projet — est dans Règles de l'agent.

La suite