--- title: "Einen Agenten anbinden" description: "So bindest du einen KI-Agenten an Notarium an: persönliches Zugriffstoken (PAT), OAuth-Connector für Web-Clients und der Transport POST /mcp." --- # Einen Agenten anbinden Ein Agent kommuniziert mit Notarium über einen einzigen Endpunkt — `POST /mcp`. Dahinter steht das eingebaute [MCP-Gateway](/docs/agents/intent-tools/): 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. ```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"}' ``` ## 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 `. Das Tokenformat lautet `ntp__`: 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). > [!important] 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: 1. 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). 2. 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“). 3. `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. > [!note] 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. > [!warning] 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](/docs/agents/agent-files/) — wie jede Session von selbst mit `start_session` beginnt, statt dass du jedes Mal darum bitten musst. - [Intent-Tools](/docs/agents/intent-tools/) — der vollständige Satz aus 21 Tools und die Reihenfolge der Aufrufe. - [Sicherheit und Sichtbarkeit](/docs/agents/security/) — wie Berechtigungen bei jedem Aufruf angewendet werden. - [Schnellstart: einen Agenten anbinden](/docs/getting-started/connect-agent/) — ein minimales Beispiel von Anfang bis Ende.