Scope-Design
Jede KI-Anwendung, die über MCP auf LedgerLou zugreift, erhält genau die Scopes, die sie für ihre Aufgabe benötigt – und keine weiteren. Scopes sind die zentrale Sicherheitsschicht: Sie entscheiden, welche Tools ein Agent aufrufen darf, bevor auch nur eine einzige Zeile ins Hauptbuch geschrieben wird.
Das Scope-Format
Scopes folgen dem Format module:action. Jede Kombination aus Modul und Aktion steuert präzise, was ein Agent lesen oder schreiben darf:
| Scope | Erlaubt |
|---|---|
journal:read | Lesen von Journalbuchungen und Kontenplan-Tools |
journal:write | Ausführen von Journalbuchungen und Schreiboperationen am Kontenplan |
bank:read | Lesen von Bankkonten und Transaktionen |
bank:write | Abstimmen und Zuordnen von Banktransaktionen |
payables:read | Lesen von Lieferanten, Eingangsrechnungen und AP-Inbox |
payables:write | Anlegen von Lieferanten, Eingangsrechnungen, Review-Fällen |
receivables:read | Lesen von Kunden und Ausgangsrechnungen |
receivables:write | Anlegen von Kunden, Ausgangsrechnungen, Gutschriften |
periods:read | Periodenstatus und Lock-Zustand lesen |
periods:write | Perioden soft-locken/wiedereröffnen, Hard-Lock beantragen |
reports:read | Summen-/Saldenliste, GuV, Bilanz, BWA, DATEV-Export |
config:read | Mandanteneinstellungen, Nutzer, API-Keys lesen (nicht über OAuth) |
config:write | Mandanteneinstellungen, Migration, Steuerschlüssel ändern (nicht über OAuth) |
admin | Globaler Superscope – umfasst alle Module und Aktionen |
OAuth-Ausschluss. Die config:*-Scopes können nicht über den OAuth-Flow angefordert werden – das Verwalten von Nutzern, API-Keys und mandantenweiten Buchhaltungs-Einstellungen gehört ins Dashboard oder hinter einen Admin-API-Key. Drittanbieter-MCP-Clients, die Migration oder Steuerschlüssel-Änderungen durchführen müssen, benötigen einen mandantenseitig ausgegebenen admin-API-Key.
Refresh-Tokens. OAuth-Clients erhalten bei jedem Authorization-Code-Austausch sowohl einen access_token (standardmäßig 30 Minuten) als auch einen rotierenden refresh_token (standardmäßig 30 Tage). Ein Aufruf von /oauth/token mit grant_type=refresh_token verbraucht den vorgelegten Refresh-Token und liefert ein frisches Access-/Refresh-Paar derselben Token-Familie. Wird ein bereits verbrauchter Refresh-Token erneut vorgelegt, wird die gesamte Familie widerrufen – eine gestohlene Kopie kann die Sitzung eines Angreifers somit nicht verlängern.
CIMD. LedgerLou akzeptiert zusätzlich die URL eines Client ID Metadata Document als client_id. MCP-Clients, die ihre Metadaten öffentlich veröffentlichen, müssen sich damit nicht je Mandant einzeln registrieren. Das Dokument wird einmalig per HTTPS abgerufen (5 s Timeout, 256 KiB Limit, SSRF-geschützt), gegen ein Zod-Schema validiert, 24 Stunden lang gecached und per If-None-Match aktualisiert. Der admin-Superscope und config:* werden CIMD-Clients nicht gewährt — Admin-Funktionen erfordern weiterhin einen mandantenseitig ausgegebenen Admin-Key.
Empfohlene Rollentrennung
Statt eines universellen Schlüssels pro KI-Integration empfehlen wir eine klare Rollentrennung: ein Agent, ein Zweck, minimale Scopes.
Liest Daten, erstellt Auswertungen, beantwortet Fragen und kann zusätzlich den Kontenplan nachschlagen. Kann nichts schreiben – kein Risiko fehlerhafter Buchungen.
Erstellt Journalbuchungen, pflegt Lieferanten/Kunden, bucht Ein- und Ausgangsrechnungen und stimmt Banktransaktionen ab. Kein Zugriff auf Admin- oder Mandanten-Konfigurations-Funktionen.
Scopes steuern die Skill-Sichtbarkeit
Scopes gaten nicht nur, welche Tools ein Aufrufer ausführen darf – sie bestimmen auch, welche Skills (MCP-Prompts) in prompts/list überhaupt erscheinen. Ein Skill wird nur freigegeben, wenn der Aufrufer alle seiner erforderlichen Scopes hält. So bleibt die Palette des Agenten fokussiert und er lädt keine Playbooks, die er ohnehin nicht ausführen könnte.
| Skill | Erforderliche Scopes |
|---|---|
process_incoming_invoice | payables:read, payables:write, journal:read, journal:write |
process_outgoing_invoice | receivables:read, receivables:write, journal:write, bank:read, bank:write |
reconcile_bank_transactions | bank:read, bank:write, journal:read |
tenant_setup_migration | admin – nur admin; für OAuth-Clients unsichtbar, da config:write benötigt wird |
Der admin-Superscope erfüllt die Anforderungen jedes Skills. OAuth-Clients sehen tenant_setup_migration niemals, da die Migration mandantenweite Konfiguration verändert – das bleibt Dashboard und admin-gekeyten MCP-Clients vorbehalten.
Guardrails, die sich bewährt haben
Jeder Agent erhält nur die Scopes, die er für seine konkrete Aufgabe benötigt. Ein Analyse-Agent braucht kein write; ein Buchungs-Agent braucht kein admin.
Sensible Tools – insbesondere write-Operationen auf dem Hauptbuch – sollten stets eine explizite Bestätigung durch den Nutzer erfordern, bevor der Agent sie ausführt.
Verwenden Sie einen dedizierten Key bzw. Token pro Integration. So lässt sich im Verdachtsfall ein einzelner Schlüssel widerrufen, ohne andere Integrationen zu stören.
Produktive Keys dürfen niemals im Frontend, in Browser-Erweiterungen oder in Client-seitigem Code liegen. MCP-Verbindungen gehören auf den Server, nicht in die App des Nutzers.
Key-Strategie in der Praxis
- 1 Erstellen Sie einen dedizierten API-Key oder OAuth-Client pro Integration – niemals einen Key über mehrere Systeme hinweg teilen.
- 2 Wählen Sie Scopes beim Verbinden bewusst aus: Vergeben Sie nur die Module, die der Agent tatsächlich benötigt.
- 3 Rotieren Sie Keys regelmäßig – insbesondere nach personellen Änderungen oder beim Austausch einer Integration.
- 4 Bei Verdacht auf Kompromittierung sofort widerrufen: Dashboard → Connected Apps → Verbindung widerrufen.
LedgerLou verwaltet GoBD-relevante Buchhaltungsdaten. Ein Agent mit zu weit gefassten Scopes kann im Fehlerfall Buchungen erzeugen, die sich nur schwer rückgängig machen lassen – das Hauptbuch ist append-only. Ein klares Scope-Design ist daher kein Nice-to-have, sondern Bestandteil der Compliance-Architektur.