MCP-Server für Finanzdaten sicher betreiben

Gehostet statt selbst betrieben

Der MCP-Server läuft gehostet unter https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp und spricht Streamable HTTP mit zustandslosen JSON-Antworten; er nimmt nur POST an. Er ist ein dünner Adapter vor der REST-API: Jeder Werkzeugaufruf geht mit dem Schlüssel des Aufrufers an dieselbe API, die auch eigene Software nutzt. Mandantentrennung, Rechte und alle GoBD-Prüfungen sitzen damit an genau einer Stelle.

Ein Paket zum Selbstbetrieb ist derzeit nicht veröffentlicht. KI-Programme, die keine eigene Kopfzeile senden können, verbinden sich über die Brücke mcp-remote, die auf Ihrem Rechner läuft und an den gehosteten Server weiterreicht. Eine Anfrage darf höchstens 10 MB groß sein; Belege bis rund 7 MB lassen sich über den MCP-Server einliefern, größere bis 20 MB per REST.

Der Schlüssel: Aufbau, Speicherung, Lebensdauer

• Aufbau: jab_live_ und 40 zufällige Zeichen aus einem kryptografischen Zufallsgenerator. Der Klartext erscheint einmal beim Anlegen; gespeichert wird nur sein SHA-256-Hash, angezeigt danach nur ein kurzes Präfix zur Wiedererkennung.
• Lebensdauer: 30 Tage, 90 Tage oder ein Jahr zur Wahl, serverseitig höchstens 366 Tage. GET /v1/ nennt Ablaufdatum und verbleibende Tage, damit Ihr Programm rechtzeitig erneuern kann.
• Verwaltung: Anlegen, Verlängern und Widerrufen nur in der App, nur durch Administratoren und Ersteller und jeweils mit zweitem Faktor. Verlängern ändert nur das Ablaufdatum; die Rechte stehen mit dem Schlüssel fest – für andere Rechte legen Sie einen neuen an.
• Bindung an den Inhaber: Bei jedem Aufruf prüft der Server, ob der Ersteller noch Bearbeiter der Gesellschaft ist. Verliert er Mitgliedschaft oder Rolle, widerruft die Software seine Schlüssel.

Den Schlüssel richtig ablegen

Der Schlüssel gehört in eine Umgebungsvariable oder einen Passwortmanager, nie in den Chat und nie in ein Repository. Für Claude Code zwei Wege:

# Schlüssel einmal in die Umgebung (z. B. aus Ihrem Passwortmanager)
export JAB_API_KEY="jab_live_…"

# Variante 1: nur für Sie, gespeichert in Ihrer eigenen Claude-Konfiguration
claude mcp add --transport http --scope user buchhaltung \
  https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp \
  --header "Authorization: Bearer $JAB_API_KEY"

# Variante 2: .mcp.json im Projekt – enthält nur den Variablennamen
{
  "mcpServers": {
    "buchhaltung": {
      "type": "http",
      "url": "https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp",
      "headers": { "Authorization": "Bearer ${JAB_API_KEY}" }
    }
  }
}

Bei Variante 1 setzt Ihre Shell den Wert ein, und Claude Code legt ihn in der Konfiguration Ihres Benutzerkontos ab. Laut Dokumentation von Claude Code ist die Projektdatei .mcp.json dafür gedacht, ins Repository eingecheckt zu werden; sie unterstützt Umgebungsvariablen in der Form ${VAR}, sodass dort nur der Name steht. Die Server-Anweisung verbietet dem Agenten, den Schlüssel in ein Feld oder eine Nachricht zu schreiben, und Downloads beschreibt der Server immer mit dem Schlüssel aus einer Umgebungsvariable. Verwenden Sie Schlüssel nur serverseitig, nicht in einer Webseite im Browser.

Was der Server bei jedem Aufruf prüft

• Schlüssel gültig, nicht widerrufen, nicht abgelaufen; der Inhaber hat noch seine Rolle; das Modul der Gesellschaft ist aktiv; eine überfällige Rechnung sperrt den Zugang (402).
• Gesellschaft aus dem Schlüssel, nie aus der Anfrage; tools/list zeigt nur Werkzeuge, die der Schlüssel benutzen darf.
• Argumente gegen das Schema des Werkzeugs, Schreibaufrufe gegen das veröffentlichte Schema der API; unbekannte Felder werden abgewiesen.
• Anfragegrenzen: 120 je Minute und Schlüssel, gezählt über alle Server-Instanzen, dazu eine Grenze je IP-Adresse; bei Überschreitung 429 mit Retry-After.
• Fehler verlassen die API als error und code, ohne rohe Datenbankmeldungen.
• Lange Exporte prüfen den Schlüssel vor dem ersten Byte erneut – ein Widerruf während des Exports stoppt ihn.

Die MCP-Spezifikation verlangt von Servern, Eingaben zu prüfen, Zugriffe zu kontrollieren, Aufrufe zu begrenzen und Ausgaben zu bereinigen. Die Liste oben zeigt, wie der Buchhaltungs-Server das umsetzt.

Welche Daten durch das Modell gehen

Dateien, die byte-genau bleiben müssen, gibt der Server nicht als Text weiter: Buchungsstapel aus Kanzlei Software, das GoBD-Paket, das Belegarchiv, Originalbelege und Jahresabschluss-Dateien. Das Werkzeug nennt stattdessen den Download-Weg samt curl-Aufruf mit dem Schlüssel aus einer Umgebungsvariable. Als Text und damit an das Modell gehen dagegen Journal und Saldenliste als CSV (export_bookkeeping), der Inhalt eines ausgestellten Jahresabschlusses (get_annual_report) und Offenlegungsdateien als XML (download_disclosure_file) – rufen Sie diese nur auf, wenn das Modell sie wirklich lesen soll.

Rechte und Schlüssel je Aufgabe

• Ein Schlüssel je Agent und Aufgabe, mit sprechender Bezeichnung; so widerrufen Sie gezielt einen, ohne die anderen anzuhalten.
• read für Auswertungen, write nur für den buchenden Agenten; send, webhooks und finalize einzeln und nur bei Bedarf.
• Gesellschaften nur mit dem Steuer-Modul erhalten Schlüssel mit Lesen und Schreiben, die nur Steuer-Routen und Stammdaten erreichen.
• Webhooks nehmen nur öffentliche https-Adressen an; der Inhaber des Schlüssels erfährt per E-Mail von jedem neuen Abonnement, und ein Widerruf des Schlüssels schaltet seine Webhooks ab.
• Ungenutzte Schlüssel widerrufen: Die Spalte „Zuletzt genutzt“ und die API-Nutzung der letzten 30 Tage zeigen, welche noch gebraucht werden.

Mehrere MCP-Server in einer Sitzung

Viele KI-Programme verbinden mehrere Server gleichzeitig. Der Buchhaltungs-Server sieht die anderen nicht und kann nicht verhindern, dass ein Agent gelesene Zahlen an ein Werkzeug eines anderen Servers weitergibt. Die Dokumentation von Claude Code rät, jedem Server vor dem Verbinden zu vertrauen, und warnt, dass Server, die externe Inhalte abrufen, ein Risiko für Prompt Injection mitbringen. Halten Sie Schlüssel mit Schreibrecht deshalb aus Sitzungen mit Web- oder Mailzugriff heraus oder bestätigen Sie dort jeden Aufruf.

Grenzen

• Ein Schlüssel ist ein statisches Geheimnis: Wer ihn hat, kann ihn bis zum Widerruf oder Ablauf nutzen. Der zweite Faktor schützt das Anlegen, nicht die Verwendung.
• Ihr Rechner, die Konfiguration Ihres KI-Programms und der Modellanbieter liegen außerhalb unseres Einflusses.
• Eine OAuth-Anmeldung bietet der MCP-Server derzeit nicht an; Programme, die nur OAuth kennen – etwa ChatGPT im Browser oder claude.ai im Browser –, lassen sich derzeit nicht direkt verbinden.
• Die Regeln des Servers schützen die Buchhaltung, nicht die Entscheidungen des Modells: Eine formal richtige, inhaltlich falsche Buchung nimmt er an.

Häufige Fragen

Wo speichere ich den API-Schlüssel am sichersten?

In einer Umgebungsvariable oder einem Passwortmanager, aus dem Ihr KI-Programm ihn liest. In Claude Code legt --scope user ihn in Ihrer eigenen Konfiguration ab; eine .mcp.json im Projekt enthält nur den Variablennamen. Nie in den Chat, nie ins Repository.

Was tue ich, wenn mein Schlüssel abgeflossen ist?

Widerrufen Sie ihn sofort im Bereich „KI-Agent & API“ – der nächste Aufruf wird abgewiesen, und seine Webhooks werden abgeschaltet. Prüfen Sie danach die API-Nutzung des Schlüssels und legen Sie einen neuen an.

Gilt ein Schlüssel für mehrere Gesellschaften?

Nein. Jeder Schlüssel gilt für genau eine Gesellschaft, die sich aus dem Schlüssel ergibt. Für eine weitere Gesellschaft legen Sie dort einen eigenen Schlüssel an.

Kann ich die Rechte eines Schlüssels nachträglich ändern?

Nein. Rechte stehen mit dem Schlüssel fest; Verlängern ändert nur das Ablaufdatum. Brauchen Sie andere Rechte, legen Sie einen neuen Schlüssel an und widerrufen den alten.

Wie viele Anfragen erlaubt der Server?

120 Anfragen pro Minute je Schlüssel. Darüber antwortet er mit 429 und nennt im Kopf Retry-After, wie lange Ihr Programm warten soll.

Kann ich den MCP-Server selbst betreiben?

Derzeit nicht: Ein Paket zum Selbstbetrieb ist nicht veröffentlicht. Sie nutzen den gehosteten Server – direkt mit Kopfzeile oder über die Brücke mcp-remote auf Ihrem Rechner.