NotariumDokumentation
Dokumentationsversion: latest
DE

Einen Agenten anbinden

Das Wesentliche an Notarium ist, dass ein und dieselbe Wissensbasis dem Menschen und dem KI-Agenten gleichermaßen offensteht. Du arbeitest über den Web-Editor, der Agent über den eingebauten MCP-Endpunkt — und seine Änderungen werden versioniert, durch Zugriffsrechte begrenzt und mit Provenienz signiert, genau wie deine. Dafür musst du keinen separaten Dienst aufsetzen: Das MCP-Gateway läuft im selben Prozess und auf demselben Port wie die Weboberfläche.

Diese Seite ist der schnelle Weg: ein Token ausstellen, den Agenten auf den Endpunkt richten und sich vergewissern, dass der Agent deine Wissensbasis sieht. Der vollständige Kontrakt (Tools, Aufrufkonventionen, Gedächtnis, Audit, Sicherheit) steht im Abschnitt Agenten und MCP.

Schritt 1. Ein Token ausstellen

Der Agent authentifiziert sich mit einem persönlichen Zugriffstoken (PAT). Stell es in den Einstellungen deines Kontos aus (Bereich Tokens) — dort legst du auch fest:

  • den Scope — read oder write (die Berechtigungsobergrenze des Tokens);
  • eine optionale Einschränkung auf Spaces — welche Spaces erreichbar sind;
  • eine optionale Gültigkeitsdauer.

Das Token hat die Form ntp_<id>_<secret> und wird genau einmal angezeigt — kopier es sofort. Ein geleaktes PAT verschafft keine zusätzlichen Rechte: Verwaltungsaktionen (Tokens ausstellen, Mitgliedschaft, Spaces anlegen) sind nur in einer menschlichen Session verfügbar, niemals per Token.

Die Rechte eines Tokens sind die Obergrenze des Agenten

Ein Read-only-Token sieht die schreibenden Tools schlicht nicht: Sie tauchen in seinem Toolset gar nicht erst auf. Der Space einer anderen Person bleibt prinzipbedingt unerreichbar — ohne Ausnahme. Gib einem Agenten genau die Rechte, die die Aufgabe braucht.

Schritt 2. Den Agenten auf den Endpunkt richten

Richte den Agenten (oder MCP-Client) auf den Endpunkt aus:

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

Der Transport ist streamable-HTTP aus dem offiziellen MCP-SDK, stateless, eine JSON-Antwort pro Anfrage (GET/DELETE antworten mit 405). Der Endpunkt ist kompatibel mit dem MCP-Connector der Claude API und jedem HTTP-MCP-Client.

Die Web-Connectors von claude.ai und chatgpt.com

In die Custom-Connectors der Weboberflächen lässt sich kein PAT einfügen — sie arbeiten ausschließlich über OAuth. Notarium bringt eine schlanke OAuth-Fassade mit: Der Connector meldet sich mit deiner Session an und erhält ein Token, das demselben Principal zugeordnet wird. Details stehen im Abschnitt Einen Agenten anbinden.

Schritt 3. Erster Aufruf — start_session

In einer neuen Session ruft der Agent zuerst start_session auf. In einer einzigen Anfrage erhält er dein Profil, die Liste der verfügbaren Projekte und das Delta der Änderungen seit seinem letzten Besuch — und wenn du einen project-Hinweis übergibst, dazu einen kompakten Index dieses Projekts. Das ist der Kontext, mit dem die Arbeit beginnen sollte.

Ab da folgt der gewohnte Ablauf: die Struktur sichten (list_notes, recent_activity), vor dem Schreiben suchen (search — Dedup), dann schreiben (create_note, edit_note, Gedächtnis über remember_about_user / remember_about_project). Der Agent arbeitet über einen schmalen, auf konkrete Aufgaben zugeschnittenen Satz von Tools statt über universelle Lese-/Schreiboperationen — jedes Tool erzwingt sicheres Verhalten (die Klasse der Notiz, die Sichtbarkeit, die Provenienz, eine Versionsprüfung beim Speichern, damit fremde Änderungen nicht überschrieben werden).

Setz eine none-Instanz nicht dem Netz aus

Im Modus AUTH_MODE=none ist der /mcp-Endpunkt ohne Token offen (ein einziger All-Access-Principal). Das ist praktisch für den Desktop-Einsatz und vertrauenswürdige Umgebungen, aber eine solche Instanz darf niemals einem öffentlichen Netz ausgesetzt werden.

Schritt 4. Das in den Regeln des Agenten festhalten

Welches Tool aufgerufen wird, entscheidet das Modell selbst. Deshalb lohnt es sich, „start_session zuerst aufrufen“ einmal in den dauerhaften Anweisungen des Agenten festzuhalten (CLAUDE.md, AGENTS.md, Cursor rules, Systemprompt) — zusammen mit dem Handle deines Projekts:

- Rufe zu Beginn einer neuen Session `start_session(project: "acme/website")`
  auf dem MCP-Server `notarium` auf.
- Vor jedem Schreiben immer zuerst `search(...)` — lege keine Duplikate an.

Ohne das musst du den Agenten jedes Mal aufs Neue von Hand auf deine Wissensbasis hinweisen. Ausführlich — mit einer Karte deines Kanons und der Trennung zwischen globalen und projektbezogenen Regeln — steht das unter Agenten-Regeln.

Weiter