Einen Agenten anbinden

Ein Agent kommuniziert mit Notarium über einen einzigen Endpunkt — POST /mcp. Dahinter steht das eingebaute MCP-Gateway: dieselbe Engine, dieselben Daten wie im Web-Editor, aber mit einem eng gefassten Satz von Intent-Tools statt direktem Zugriff auf den Datenspeicher. Für die Anbindung gibt es zwei Wege: ein persönliches Zugriffstoken (PAT) für programmatische Clients oder einen OAuth-Connector für claude.ai und chatgpt.com im Browser.

Transport: POST /mcp

Der Endpunkt POST /mcp implementiert den Streamable-HTTP-Transport des offiziellen @modelcontextprotocol/sdk. Er arbeitet zustandslos: Jede Anfrage startet einen frischen Server mit den Berechtigungen deines Tokens und liefert genau eine JSON-Antwort zurück — keinen SSE-Stream. GET und DELETE antworten mit 405: Vom Server ausgehende Streams gibt es hier nicht.

Der Endpunkt ist kompatibel mit dem MCP-Connector der Claude API, mit Claude Code und mit jedem HTTP-MCP-Client, der ein Bearer-Token mitschicken kann.

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"}'

Weg 1. Persönliches Zugriffstoken (PAT)

Das PAT ist der Hauptweg für programmatische Clients (Claude API, Claude Code, konfigurierbare MCP-Clients). Übergeben wird es im Header Authorization: Bearer <pat>.

Das Tokenformat lautet ntp_<id>_<secret>: Das Präfix ntp_ macht das Token in Logs und Leaks leicht erkennbar, der id-Teil dient dem schnellen Nachschlagen, und das Secret liegt in der Datenbank nur als Hash — zu sehen bekommst du es genau einmal, bei der Ausstellung.

Ein Token lässt sich auf zwei Wegen ausstellen:

In der UI — im Token-Bereich der Einstellungen. Du vergibst einen Namen, eine Stufe (read oder write) und optional einen auf bestimmte Spaces eingeschränkten Scope sowie eine Gültigkeitsdauer.
Über die API — POST /api/me/tokens. Das erfordert die Berechtigung self:manage: Ein Token kannst nur du selbst ausstellen, über eine Session, niemals der Agent (ein geleaktes Token kann kein neues ausstellen).

Die Berechtigungen eines Tokens sind eine Obergrenze

Ein read-Token sieht die schreibenden Tools in tools/list gar nicht erst — es ist nicht so, dass sie auftauchen und dann ablehnen; sie fehlen schlicht in der Liste. Der Satz von Spaces im Token bestimmt, welche Spaces der Agent erreichen kann; alles außerhalb bleibt prinzipbedingt unerreichbar. Die Berechtigungen lassen sich nach der Ausstellung ändern (Name, Stufe, Satz von Spaces), ohne das Secret neu zu erzeugen — die Änderung greift ab dem nächsten Aufruf.

Weg 2. OAuth-Connector für Web-Clients

Die Weboberflächen von claude.ai und chatgpt.com akzeptieren beim Hinzufügen eines „custom connector“ ausschließlich OAuth — ein Feld zum Einfügen eines Bearer-Tokens gibt es dort nicht. Dafür bringt Notarium eine schlanke OAuth-2.1-Fassade mit: Notarium ist sein eigener Authorization Server — es gibt niemanden, an den sich das delegieren ließe, denn beim Self-Hosting liegen die Konten bei dir.

So läuft das ab:

Eine Anfrage an POST /mcp ohne Token beantwortet der Server mit 401 und einem WWW-Authenticate-Header, der auf die Discovery-Dokumente verweist (RFC 9728 / RFC 8414).
Der Client durchläuft GET /oauth/authorize — du meldest dich mit deiner laufenden Session an und wählst im Consent-Dialog die Spaces aus (Mehrfachauswahl, voreingestellt „All spaces“).
POST /oauth/token mit PKCE (Methode S256) stellt ein Access-Token (nto_…) aus — und mit offline_access zusätzlich ein Refresh-Token (ntr_…).

Das ausgestellte Token verweist auf denselben Principal und durchläuft dieselbe Prüfstelle wie ein PAT oder eine Session. Seine Stufe ist read oder write, aber niemals manage: Ein geleaktes Connector-Token kann kein neues Token ausstellen und keinen Zugriff gewähren. Verbindungen verwalten und ihre Stufe oder ihre Spaces änderst du im Bereich Connected apps — ein erneuter Consent ist dafür nicht nötig.

Claude und ChatGPT werden über OAuth angebunden

In ChatGPT wird Notarium als gewöhnlicher Connector auf demselben OAuth hinzugefügt — genau wie in claude.ai: Anmeldung mit der laufenden Session, Auswahl der Spaces im Consent-Dialog, und der Agent sieht deinen gewohnten Satz von Intent-Tools.

Der Modus none: ohne Token

Läuft eine Instanz mit AUTH_MODE=none (Desktop, Dev, vertrauenswürdiges Intranet — der Betreiber schaltet die Authentifizierung bewusst ab), arbeitet das Gateway ohne Authentifizierung: /mcp tritt als ein einziger All-Access-Principal auf, und claude.ai/ChatGPT nehmen es ohne Weiteres als authless Connector auf. Eine OAuth-Fassade gibt es in diesem Modus nicht.

Ein authless Server ist öffentlich

Im Modus none gilt: Wer die URL kennt, kann sie aufrufen. Vertretbar ist das nur für Single-User-Setups, Demos oder ein vertrauenswürdiges Netz. Für eine Mehrbenutzer-Instanz nimm AUTH_MODE=password (die Voreinstellung).

Weiter

Agentenregeln — wie jede Session von selbst mit start_session beginnt, statt dass du jedes Mal darum bitten musst.
Intent-Tools — der vollständige Satz aus 21 Tools und die Reihenfolge der Aufrufe.
Sicherheit und Sichtbarkeit — wie Berechtigungen bei jedem Aufruf angewendet werden.
Schnellstart: einen Agenten anbinden — ein minimales Beispiel von Anfang bis Ende.