1. Was ist MCP und was bietet CompanyFin?
Das Model Context Protocol (MCP) ist ein von Anthropic initiierter offener Standard. Er löst das Problem, dass KI-Modelle keinen direkten Zugriff auf aktuelle, geschützte Unternehmensdaten haben. Statt Daten als CSV zu exportieren und in ein Chatfenster zu kopieren, ruft Ihr KI-Assistent die benötigten Daten bei Bedarf gezielt in Echtzeit ab.
CompanyFin fungiert dabei als MCP-Server. Er bietet Ihrem Agenten drei Dinge an:
- Tools: 35 Funktionen zum Lesen, Zuarbeiten und (mit Ihrer Erlaubnis) Entscheiden. Sie sind in Abschnitt 5 vollständig beschrieben.
- Ressourcen: Anleitungen für den Agenten (Arbeitsablauf, Vertrauensstufen).
- Prompts: Vorlagen wie „Monat fertigstellen“, die Ihr Client als Auswahl anbietet.
CompanyFin ist dabei bewusst agentenfreundlich, nicht agentengesteuert: Stimmige Belege bucht CompanyFin automatisch, Unsicherheiten werden als Prüfvermerk für Ihre Steuerberatung gespeichert. Der Agent erledigt den Teil, der sonst bei Ihnen liegt. Das sind offene Rückfragen, fehlende Belege und, wenn Sie es erlauben, Zuordnungen und Freigaben.
2. Schlüssel und Vertrauensstufe einrichten
Der Zugang ist ein API-Schlüssel, den nur Sie erstellen und jederzeit widerrufen können. Voraussetzung ist der Pro-Tarif.
- Einstellungen öffnen: Melden Sie sich unter
app.companyfin.dean und öffnen Sie Einstellungen → API und MCP. - Nur lesen? Dann direkt weiter mit Schritt 4. Ein Schlüssel der Stufe Lesen braucht keine Integration.
- Integration anlegen (nur für Zuarbeiten und Buchhalter): Erstellen Sie im Bereich Integrationen eine Integration, zum Beispiel „Claude Buchhaltung“. Sie bündelt alles, was dieser Agent anlegt (Entwürfe, Vorschläge), und macht es im Auditprotokoll zuordenbar. Dafür brauchen Sie die Berechtigung, Integrationen zu verwalten.
- Schlüssel erstellen: Vergeben Sie einen Namen, wählen Sie die Vertrauensstufe (Lesen, Zuarbeiten, Buchhalter) und bei Schreibrechten die Integration und ein Ablaufdatum (höchstens 180 Tage).
- Schlüssel kopieren: Der Schlüssel beginnt mit
cf_live_und wird nur einmal angezeigt. Speichern Sie ihn wie ein Passwort, zum Beispiel in einem Passwortmanager.
3. Verbindung herstellen
Der MCP-Server ist ein Remote-Server (Streamable HTTP) unter
https://app.companyfin.de/api/v2/mcp/Der Schlüssel wird bei jeder Anfrage als HTTP-Header mitgeschickt, entweder als X-API-Key: cf_live_… oder als Authorization: Bearer cf_live_…. Ersetzen Sie in den Beispielen DEIN_API_SCHLUESSEL durch Ihren Schlüssel.
Claude Code
Ein Befehl im Terminal registriert den Server:
claude mcp add --transport http companyfin https://app.companyfin.de/api/v2/mcp/ \
--header "X-API-Key: DEIN_API_SCHLUESSEL"Mit --scope user gilt die Verbindung in allen Projekten, ohne diese Option nur im aktuellen. Mit claude mcp list oder dem Befehl /mcp in einer Sitzung prüfen Sie, ob der Server verbunden ist. Wollen Sie die Konfiguration in einer gemeinsam genutzten .mcp.json ablegen, tragen Sie den Schlüssel nicht fest ein, sondern als Umgebungsvariable:
{
"mcpServers": {
"companyfin": {
"type": "http",
"url": "https://app.companyfin.de/api/v2/mcp/",
"headers": { "X-API-Key": "${COMPANYFIN_API_KEY}" }
}
}
}Cursor und andere Clients mit Remote-MCP
{
"mcpServers": {
"companyfin": {
"url": "https://app.companyfin.de/api/v2/mcp/",
"headers": { "X-API-Key": "DEIN_API_SCHLUESSEL" }
}
}
}Bei Cursor liegt die Datei unter ~/.cursor/mcp.json (global) oder .cursor/mcp.json (Projekt). Andere Clients benennen die Felder teils anders; entscheidend sind die URL und der Header.
Claude Desktop
Claude Desktop bindet Server über claude_desktop_config.json ein (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Remote-Server mit API-Schlüssel verbinden Sie über den Adapter mcp-remote, der Node.js voraussetzt:
{
"mcpServers": {
"companyfin": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.companyfin.de/api/v2/mcp/",
"--header", "Authorization:${COMPANYFIN_AUTH}"],
"env": { "COMPANYFIN_AUTH": "Bearer DEIN_API_SCHLUESSEL" }
}
}
}Starten Sie Claude Desktop danach neu. Der Server erscheint in der Liste der Verbindungen.
Älterer Transport: SSE
Clients, die nur das ältere SSE-Protokoll beherrschen, verwenden https://app.companyfin.de/api/v1/mcp/sse/ mit denselben Headern. Bevorzugen Sie nach Möglichkeit Streamable HTTP.
Verbindung testen
- Fragen Sie Ihren Agenten: „Was ist in CompanyFin gerade offen?“ Er sollte
get_work_queueaufrufen und die Arbeitsliste zusammenfassen. - Antwortet er mit einem Authentifizierungsfehler, prüfen Sie Header und Schlüssel. Die häufigsten Ursachen stehen in Abschnitt 9.
- Für Claude gibt es zusätzlich eine Skill-Vorlage, die den Arbeitsablauf der Buchhaltung beschreibt.
4. Vertrauensstufen und Scopes
Finanzdaten gehören zu den sensibelsten Informationen eines Unternehmens. Deshalb vergeben Sie die Rechte Ihres Agenten bewusst. Jede Vertrauensstufe ist ein vorgefertigtes Bündel von Scopes; die Scopes bleiben die maßgebliche Berechtigung.
| Vertrauensstufe | Was der Agent darf |
|---|---|
| Lesen (Standard) | Kennzahlen, Umsätze, Belege, Arbeitsliste und Berichte abfragen. Keine Änderungen. |
| Zuarbeiten | Zusätzlich Belege einreichen und Rückfragen beantworten; CompanyFin bucht danach automatisch. Entwürfe für Sonderbuchungen und Zuordnungsvorschläge bleiben unverbindlich, bis Sie sie freigeben. |
| Buchhalter | Zusätzlich Zahlungen zuordnen, falsche Zuordnungen lösen, Vorschläge anderer Programme annehmen oder ablehnen, Buchungsvorschläge und eigene Sonderbuchungen freigeben, erkannte Duplikate auflösen sowie gebuchte Belege per Storno korrigieren oder verwerfen. Belege bleiben dabei immer aufbewahrt. |
Scopes im Detail
| Scope | Berechtigt zu | Enthalten in |
|---|---|---|
read:mcp | MCP-Discovery: Voraussetzung für jeden MCP-Zugriff | Lesen |
read:kpis, read:analytics | Kennzahlen und Analysen | Lesen |
read:transactions, read:accounts | Banktransaktionen, Bankkonten, Kontenplan | Lesen |
read:receipts | Belege, Arbeitsliste, Rückfragen, Belegstatus | Lesen |
read:reports | Bilanz, GuV, EÜR, Umsatzsteuer-Voranmeldung, Prüfvermerke | Lesen |
read:booking-drafts, write:booking-drafts | Eigene Buchungsentwürfe lesen, erstellen, ändern, verwerfen | Zuarbeiten |
read:match-proposals, write:match-proposals | Eigene Zuordnungsvorschläge | Zuarbeiten |
write:receipt-inbox | Belege einreichen (werden automatisch verarbeitet) | Zuarbeiten |
write:clarification-answers | Rückfragen beantworten | Zuarbeiten |
write:match-assignments | Zahlungen zuordnen, Vorschläge annehmen oder ablehnen | Buchhalter |
write:booking-approvals | Buchungsvorschläge freigeben | Buchhalter |
write:receipt-decisions | Duplikate als eigenen Beleg bestätigen | Buchhalter |
write:match-corrections | Falsche Zuordnungen lösen | Buchhalter |
write:booking-corrections | Per Storno korrigieren, Beleg verwerfen | Buchhalter |
write:receipts | Kategorie-Vorschläge für Belegpositionen | nur einzeln („Individuell“) |
Jede Stufe enthält die Scopes der darunterliegenden. Eine andere Kombination zeigt die Oberfläche als „Individuell“ an.
5. Tool-Referenz
Alle 35 Tools des Servers, gruppiert nach der Vertrauensstufe, ab der sie verfügbar sind. Jeder Eintrag nennt den benötigten Scope, was das Tool tut und seine Parameter. Pflichtparameter sind als „Pflicht“ gekennzeichnet. Beträge sind Dezimal-Strings in Euro (z. B. "119.00"), Datumsangaben haben das Format JJJJ-MM-TT.
Lesen: Arbeitsliste, Kennzahlen, Berichte
Diese Tools ändern nichts. Sie sind in jedem Schlüssel enthalten (Stufe Lesen). Der Scope read:mcp muss zusätzlich am Schlüssel hängen; er ist in der Stufe Lesen enthalten.
Arbeitsliste und Status
get_work_queueread:receipts
Der Startpunkt für jeden Agenten: was ist gerade offen, wie in der Arbeitsliste der App. Jeder Eintrag nennt in next_step das Tool, das ihn löst, und den dafür nötigen Scope; ohne Tool müssen Sie in der App entscheiden. Der Block automation zeigt, worauf CompanyFin noch wartet (Zahlungen, amtliche Kurse). Dort ist nichts zu tun.
category: optional: approval (Buchungsvorschlag wartet auf Freigabe), missing_info (Angabe fehlt), missing_receipt (Zahlung ohne Beleg), manual_match (Zuordnung nicht eindeutig)limit: optional, Standard 50, höchstens 100
list_open_questionsread:receipts
Offene Rückfragen, die CompanyFin zum Buchen braucht, zum Beispiel Leistungszeitraum, betriebliche Nutzung oder die Ursprungsrechnung einer Gutschrift. Jede Frage enthält answer_type, options und value_format, also genau das value-Objekt, das answer_question erwartet.
receipt_id: optional: nur Fragen dieses Belegslimit: optional, Standard 50
get_receipt_statusread:receipts
Verarbeitungs-, Zuordnungs- und Buchungsstand eines Belegs: processing_status (pending, processing, completed, review_needed, failed), match_status, workflow_state, offene Fragen und die Buchungen inklusive Prüfvermerken. Das Tool zum Nachfassen nach submit_receipt, answer_question oder assign_payment.
receipt_id: Pflicht: ID des Belegs
list_advisor_review_postingsread:reports
Buchungen, die CompanyFin automatisch mit einem Prüfvermerk für die Steuerberatung gebucht hat, neueste zuerst, mit lesbarem Vermerk. Es sind gültige Buchungen, die Ihre Steuerberatung nur prüft.
start_date, end_date: optional: Zeitraum (JJJJ-MM-TT)limit, offset: optional: Standard 25 und 0
Kennzahlen und Analysen
get_dashboard_summaryread:kpis
Die Kennzahlen des Dashboards: Umsatz, Aufwand, Ergebnis, Burn Rate, Runway, Eigenkapitalquote, Vorsteuerrisiko, Bearbeitungsdauer und Abstimmungsquote. Ohne Zeitraum wird die gesamte Historie ausgewertet.
start_date, end_date: optional: Zeitraum (JJJJ-MM-TT)
get_dashboard_analyticsread:analytics
Monatliche Zeitreihen (Erträge, Aufwände, Ergebnis, Umsatzsteuer) und die Aufteilung der Ausgaben nach Kategorien. Geeignet für Trends und Auffälligkeiten.
start_date, end_date: optional: Zeitraum (JJJJ-MM-TT)
get_startup_pnlread:analytics
Strukturierte Startup-GuV: Umsatz, Wareneinsatz (COGS), Rohertrag, Forschung & Entwicklung, Vertrieb & Marketing, Verwaltung, EBITDA und Jahresergebnis.
start_date, end_date: optional: Zeitraum (JJJJ-MM-TT)
Bank, Konten und Transaktionen
list_bank_accountsread:accounts
Angebundene Bankkonten mit IBAN und aktuellem Saldo.
search_transactionsread:transactions
Sucht Banktransaktionen nach Text, Zeitraum oder Betragsspanne, neueste zuerst. Beträge sind Dezimal-Strings.
query: optional: Textsuchestart_date, end_date: optional: Buchungsdatum von/bismin_amount, max_amount: optional: Betragsspannelimit, offset: optional: Standard 25 (höchstens 100) und 0
get_transaction_detailsread:transactions
Detailansicht einer Transaktion mit verknüpften Belegen und allen Buchungszeilen (bookings).
transaction_id: Pflicht: ID der Transaktion
get_chart_of_accountsread:accounts
Der SKR04-Kontenplan (Systemkonten plus eigene Konten) mit Salden. Die id eines Kontos ist die Konto-ID, die create_booking_draft erwartet.
account_class: optional: Kontenklasse 0 bis 9
Belege
get_invoice_detailsread:receipts
Belege und Rechnungen mit OCR-Daten, Umsatzsteuer, Positionen, verknüpften Transaktionen und Buchungen. Standardmäßig kompakt; mit include_details=true kommt die strukturierte OCR-Extraktion (structured_data) hinzu.
receipt_id: optional: genau ein Belegquery: optional: Textsuchestart_date, end_date: optional: Belegdatum von/bismin_amount, max_amount: optional: Bruttobetrag von/bisreceipt_type: optional: z. B. incoming, outgoing, otherocr_status, match_status: optional: Filter nach Verarbeitungs- bzw. Zuordnungsstatusvendor_name, invoice_number: optional: enthält-Filterlimit, offset: optional: Standard 25 (höchstens 100) und 0include_details: optional: true liefert zusätzlich structured_data
Berichte und Abschluss
get_balance_sheetread:reports
Vorläufige Bilanz nach § 266 HGB zu einem Stichtag, vor Abschlussbuchungen. Nur für bilanzierende Organisationen.
as_of: optional: Stichtag (JJJJ-MM-TT), Standard heute
get_income_statementread:reports
Vorläufige GuV nach § 275 Abs. 2 HGB (Gesamtkostenverfahren) für einen Zeitraum. Nur für bilanzierende Organisationen.
start_date, end_date: Pflicht: Zeitraum (JJJJ-MM-TT)
get_euerread:reports
Vorläufige Einnahmenüberschussrechnung nach § 4 Abs. 3 EStG für ein Kalenderjahr. Nur für EÜR-Organisationen (Kassenbasis).
year: optional: Kalenderjahr, Standard laufendes Jahr
get_vat_returnread:reports
Vorläufige Umsatzsteuer-Voranmeldung eines Monats oder Quartals aus den gebuchten Daten: Kennzahlen mit Bemessungsgrundlage und Steuer, Zahllast (Kennzahl 83), Fälligkeit und open_items. Ein offener Posten gehört in die Voranmeldung, lässt sich aber nicht zuordnen, etwa ein Verkauf ohne Steuer auf einem steuerpflichtigen Erlöskonto oder eine Eingangsrechnung mit § 13b-Fall ohne geschuldete Steuer. Es wird nichts an das Finanzamt übermittelt. Nicht für Kleinunternehmer.
year: Pflicht: Kalenderjahrperiod: Pflicht: Monat 01 bis 12 oder Quartal Q1 bis Q4
get_closing_checkread:reports
Checkliste vor dem Jahresabschluss: was den Abschluss blockiert (status blocking) und was zuerst angesehen werden sollte (status warning), etwa Bankbewegungen ohne Buchung, Belege in Verarbeitung, ausstehende AfA oder eine nicht ausgeglichene Bilanz. Der Abschluss selbst bleibt bei Ihnen in der App.
year: optional: Kalenderjahr, in dem das Geschäftsjahr endet; ohne Angabe das älteste beendete, offene Jahr
Zuarbeiten: Belege, Rückfragen, Entwürfe
Schreibende Tools der Stufe Zuarbeiten. Sie brauchen einen Schlüssel, der an eine Integration gebunden ist, und einen idempotency_key (siehe Abschnitt 9). Entwürfe und Vorschläge sind unverbindlich: Sie wirken erst, wenn Sie sie in der App freigeben oder ein Schlüssel der Stufe Buchhalter sie freigibt.
Belege und Rückfragen
submit_receiptwrite:receipt-inbox
Reicht eine Rechnung oder einen Beleg ein (PDF, Bild oder XRechnung/ZUGFeRD-XML), wie ein Upload in der App oder die Weiterleitung an das Belegpostfach. CompanyFin liest den Beleg, ordnet die Zahlung zu und bucht automatisch. Dieselbe Datei zweimal liefert den Status duplicate. Danach mit get_receipt_status nachfassen.
file_base64: Pflicht: Dateiinhalt als Base64. Es gilt das Upload-Limit der App.filename: Pflicht: Dateiname mit Endungidempotency_key: Pflicht: stabiler Schlüssel pro Datei
answer_questionwrite:clarification-answers
Beantwortet eine offene Rückfrage genau so, wie Sie es in der App täten; die Verarbeitung läuft danach automatisch weiter. Ist der Beleg schon gebucht, wird die Buchung per Storno korrigiert und neu gebucht. Nur beantworten, was sich belegen lässt (Belegtext, Ihre Unterlagen, Ihre Aussage), sonst die Frage für Sie stehen lassen.
question_id: Pflicht: ID aus list_open_questionsvalue: Pflicht: Objekt nach value_format, z. B. {"choice": "business_only"} oder {"date": "2026-10-01"}idempotency_key: Pflichtrationale: optional, höchstens 500 Zeichen: Quelle des Fakts, im Auditprotokoll gespeichert
propose_position_categorywrite:receipts
Schlägt die Leistungskategorie einer Belegposition vor (z. B. software_subscription, web_hosting, cloud_service). Unverbindlich: Es entsteht eine Rückfrage am Beleg; erst Ihre Antwort korrigiert den Beleg, lernt die Positionsregel des Lieferanten und bucht automatisch gebuchte Belege neu. Der Scope write:receipts gehört zu keiner Vertrauensstufe und muss einzeln vergeben werden (Stufe „Individuell“).
payload: Pflicht: {"receipt_id": 123, "position_index": 0, "category": "web_hosting", "rationale": "…"}idempotency_key: Pflicht
Entwürfe und Zuordnungsvorschläge
create_booking_draftwrite:booking-drafts
Legt eine prüfbare freie Buchung (Buchungsentwurf) an, für Fälle, die die Automatik nicht bucht: Privatnutzung, Abschlussbuchungen wie Rückstellungen und Steuern, Umbuchungen, selbst geschuldete Umsatzsteuer. Der Entwurf bestätigt oder exportiert nichts. Er wartet in der Arbeitsliste, bis Sie ihn freigeben oder ein Buchhalter-Schlüssel ihn mit approve_booking freigibt. Aufbau und Steuerschlüssel: Abschnitt 6.
payload: Pflicht: booking_date, description, optional receipt_id oder transaction_id, lines[] (Soll-Konto-ID, Haben-Konto-ID, amount, tax_key, tax_amount)idempotency_key: Pflicht
update_booking_draftwrite:booking-drafts
Ändert einen offenen Entwurf dieser Integration mit optimistischer Versionsprüfung. Nützlich, wenn die Freigabeprüfung etwas beanstandet.
package_id: Pflicht: ID des Entwurfspayload: Pflicht: expected_version plus mindestens eines von booking_date, description, linesidempotency_key: Pflicht
list_booking_draftsread:booking-drafts
Listet die Buchungsentwürfe dieser Integration. Es werden nur eigene Entwürfe angezeigt.
limit: optional: Standard 25, höchstens 100
get_booking_draftread:booking-drafts
Liefert einen Entwurf dieser Integration mit Version und Zeilen. Die Version brauchen Sie für Änderung, Verwerfen und Freigabe.
package_id: Pflicht: ID des Entwurfs
discard_booking_draftwrite:booking-drafts
Verwirft einen offenen Entwurf dieser Integration (Versionsprüfung). Bestätigte Buchungen werden nie berührt.
package_id: Pflicht: ID des Entwurfspayload: Pflicht: {"expected_version": 1}idempotency_key: Pflicht
propose_receipt_matchwrite:match-proposals
Legt einen unverbindlichen Zuordnungsvorschlag Beleg ↔ Transaktion an. Es entsteht weder eine wirksame Verknüpfung noch eine Buchung; Sie oder ein Buchhalter-Schlüssel entscheiden (decide_proposal).
payload: Pflicht: {"transaction_id": 1, "receipt_id": 2, "rationale": "…", "proposed_amount": {"amount": "119.00", "currency": "EUR"}}; rationale und proposed_amount sind optionalidempotency_key: Pflicht
Buchhalter: Zuordnen, Freigeben, Korrigieren
Entscheidungen, die Sie delegieren können. Es gelten dieselben Prüfungen wie in der App. Alle Tools nehmen idempotency_key (Pflicht) und rationale (optional, höchstens 500 Zeichen, wird im Auditprotokoll gespeichert). Korrekturen nur, wenn der Agent benennen kann, was falsch war. Zusätzlich zur Stufe Zuarbeiten gilt:
Zuordnen und entscheiden
assign_paymentwrite:match-assignments
Ordnet eine Banktransaktion den Belegen zu, die sie bezahlt, wie die manuelle Zuordnung in der App; CompanyFin bucht die Zahlung danach automatisch. Für Einträge der Kategorie manual_match, nachdem der Agent die Zahlung mit search_transactions gefunden und Betrag, Datum und Gegenpartei geprüft hat. Eine bestehende abweichende Zuordnung wird ersetzt, ihre nicht exportierten Zahlungsbuchungen werden freigegeben (exportierte per Storno).
transaction_id: Pflicht: ID der Transaktionreceipt_ids: Pflicht: 1 bis 20 Beleg-IDs (mehrere bei einer Sammelzahlung)idempotency_key, rationale: idempotency_key Pflicht, rationale optional
decide_proposalwrite:match-assignments
Nimmt einen Zuordnungsvorschlag eines angebundenen Programms an oder lehnt ihn ab (Arbeitslisten-Eintrag mit proposal_id). accept verknüpft Beleg und Zahlung wie assign_payment; reject verhindert, dass das Paar automatisch wieder zugeordnet wird.
proposal_id: Pflicht: ID des Vorschlagsdecision: Pflicht: accept oder rejectreason: nur bei reject: wrong_amount, wrong_partner, wrong_date, bulk_payment, partial_payment, wrong_receipt_type, duplicate oder otheridempotency_key, rationale: idempotency_key Pflicht, rationale optional
approve_bookingwrite:booking-approvals
Gibt einen Buchungsvorschlag frei, der auf Freigabe wartet, wie „Freigeben“ in der App. expected_version stammt aus get_work_queue (package_version) bzw. aus dem eigenen Entwurf; ein geänderter Vorschlag wird abgelehnt. Eine über MCP oder API entworfene freie Buchung wird mit einem Prüfvermerk für die Steuerberatung (agent_journal_entry) gebucht. Ein widersprüchlicher Vorschlag wird mit Begründung abgelehnt. Exportierte oder bestätigte Buchungen bleiben unberührt.
booking_package_id: Pflicht: ID des Buchungspaketsexpected_version: Pflicht: aktuelle Version des Paketsidempotency_key, rationale: idempotency_key Pflicht, rationale optional
dismiss_duplicatewrite:receipt-decisions
Bestätigt, dass ein als Duplikat markierter Beleg (duplicate_of_receipt_id in get_receipt_status) ein eigenes Dokument ist, zum Beispiel eine zweite Rechnung mit gleicher Nummer, aber anderer Leistung. Er wird danach normal verarbeitet und gebucht und nie wieder verglichen. Nur verwenden, wenn sich die Dokumente nachweislich unterscheiden.
receipt_id: Pflicht: ID des Belegsidempotency_key, rationale: idempotency_key Pflicht, rationale optional
Korrigieren und verwerfen (nur per Storno)
unlink_receipt_matchwrite:match-corrections
Löst die Belegzuordnung einer Transaktion (falsche Zuordnung) und gibt deren nicht exportierte Zahlungsbuchungen frei, wie „Zuordnung ablehnen“ in der App. Eine bereits nach DATEV exportierte Zahlungsbuchung wird mit einer Spiegelbuchung (Storno) zum ursprünglichen Datum aufgehoben; andere exportierte Buchungen, abgeschlossene Geschäftsjahre und Buchungen mit Korrekturhistorie werden abgelehnt. Das Paar gilt als abgelehnt und wird nicht erneut vorgeschlagen.
transaction_id: Pflicht: ID der Transaktionreason: Pflicht: wrong_amount, wrong_partner, wrong_date, bulk_payment, partial_payment, wrong_receipt_type, duplicate oder otheridempotency_key: Pflicht
preview_booking_correctionwrite:booking-corrections
Zeigt, was die Korrektur eines gebuchten Belegs bewirken würde, wie „Korrigieren“ in der App: welche Buchungen der Kette (Rechnung, Folgebuchungen, Skonto, Gutschriften) zu ihrem ursprünglichen Datum storniert werden, welche Zahlungsbuchungen bleiben, und den preview_token für correct_booking. Es ändert sich nichts.
booking_package_id: Pflicht: Rechnungsbuchung des Belegs (siehe bookings in get_receipt_status)
correct_bookingwrite:booking-corrections
Korrigiert einen gebuchten Beleg: die Buchungskette wird per Storno zum ursprünglichen Datum aufgehoben und CompanyFin bucht den Beleg aus den aktuellen Angaben neu. Zuvor preview_booking_correction aufrufen und dessen Token übergeben; eine veränderte Kette wird abgelehnt. Nichts wird gelöscht, abgeschlossene Geschäftsjahre werden abgelehnt.
booking_package_id: Pflicht: Rechnungsbuchung des Belegspreview_token: Pflicht: Token aus preview_booking_correctionreason_code: Pflicht: incorrect_entry (Buchung war falsch), facts_changed (Angaben des Belegs haben sich geändert) oder profile_changed (Firmeneinstellungen haben sich geändert)idempotency_key, rationale: idempotency_key Pflicht, rationale optional
reverse_bookingwrite:booking-corrections
Storniert eine bestätigte manuelle Buchung, die Sie in der App erfasst haben, wie „Stornieren“ dort: Spiegelbuchung zum selben Datum. Nur einfache manuelle Buchungen ohne Beleg, Zahlung, Steuer oder Export; bei Buchungen eines Belegs correct_booking oder discard_receipt verwenden.
booking_package_id: Pflicht: ID des Buchungspaketsreason_code: Pflicht: incorrect_entry oder duplicate_entryidempotency_key, rationale: idempotency_key Pflicht, rationale optional
discard_receiptwrite:booking-corrections
Verwirft einen Beleg, der kein buchbares Dokument ist oder versehentlich eingereicht wurde (Bestellbestätigung, Mahnung, zweite Kopie), wie „Verwerfen“ in der App: Buchungen werden storniert, Zahlungen gelöst, der Beleg verschwindet aus der Liste. Die Datei bleibt für die Aufbewahrungsfrist gespeichert; ein Agent löscht nie einen Beleg. Abgeschlossene Geschäftsjahre und Belege, die mit anderen Buchungen geteilt sind, werden abgelehnt.
receipt_id: Pflicht: ID des Belegsidempotency_key, rationale: idempotency_key Pflicht, rationale optional
6. Freie Buchungen und Steuerschlüssel
Für Vorgänge ohne Fachregel kann der Agent mit create_booking_draft eine freie Buchung entwerfen. Beispiele sind Privatnutzung bei Einzelunternehmen, Rückstellungen und Steuern zum Jahresende oder die selbst geschuldete Umsatzsteuer nach § 13b UStG. Der Entwurf wartet in Ihrer Arbeitsliste auf Freigabe. Mit der Stufe Buchhalter kann der Agent ihn selbst freigeben (approve_booking). Die Buchung trägt dann einen Prüfvermerk für Ihre Steuerberatung.
{
"booking_date": "2026-12-31",
"description": "Rückstellung Abschlusskosten 2026 gemäß Angebot der Kanzlei vom 12.11.2026",
"lines": [
{
"debit_account_id": 101,
"credit_account_id": 202,
"amount": { "amount": "1500.00", "currency": "EUR" },
"tax_key": "ohne"
}
]
}debit_account_idundcredit_account_idsind dieid-Werte ausget_chart_of_accounts, nicht die Kontonummern.descriptionsoll sagen, was gebucht wird und auf welcher Grundlage. Sie bleibt im Auditprotokoll.- Optional:
receipt_idodertransaction_idverknüpfen den Entwurf mit einem Beleg oder einer Zahlung. Höchstens 20 Zeilen je Entwurf, nur Euro. - Die Prüfungen laufen bei der Freigabe und nennen den Grund einer Ablehnung. Danach den Entwurf mit
update_booking_draftkorrigieren.
| tax_key | Bedeutung | Betrag / tax_amount |
|---|---|---|
ohne | Keine Umsatzsteuer | tax_amount 0 |
VSt19, VSt7 | Vorsteuer 19 % bzw. 7 % | Betrag brutto, tax_amount = enthaltene Steuer |
USt19, USt7 | Umsatzsteuer 19 % bzw. 7 % | Betrag brutto, tax_amount = enthaltene Steuer |
RC19, RC7 | Steuerschuld des Leistungsempfängers, § 13b UStG (Lieferant aus der EU) | Betrag netto, tax_amount = geschuldete Steuer |
RC19D | § 13b UStG, Lieferant aus einem Drittland | Betrag netto, tax_amount = geschuldete Steuer |
IGE19, IGE7 | Innergemeinschaftlicher Erwerb | Betrag netto, tax_amount = geschuldete Steuer |
Bei RC… und IGE… braucht derselbe Entwurf zusätzlich die Steuerzeile ohne Schlüssel: 1407 an 3837 (RC19, RC19D), 1408 an 3835 (RC7), 1404 an 3804 (IGE19) bzw. 1402 an 3802 (IGE7). Ein Beleg, dessen Rechnung bereits gebucht ist, darf nicht noch einmal auf 3300 oder 1200 gebucht werden. Wie ein Agent solche Fälle sauber löst, steht in der Ressource companyfin://guide/agent-workflow (Abschnitt „Sonderfälle“).
7. Ressourcen und fertige Prompts
Neben den Tools liefert der Server Anleitungen und Vorlagen, die Ihr Client anzeigt oder dem Agenten bereitstellt.
| Name | Art | Inhalt |
|---|---|---|
companyfin://guide/agent-workflow | Ressource | Arbeitsablauf, Regeln und Sonderfälle für den Agenten |
companyfin://guide/trust-levels | Ressource | Vertrauensstufen und deren Scopes |
monatsabschluss | Prompt (month: JJJJ-MM) | Einen Monat fertigstellen: Arbeitsliste, Rückfragen, fehlende Belege, Zuordnungen, Bericht |
belege_nachreichen | Prompt | Zahlungen ohne Beleg finden und die Rechnungen einreichen |
rueckfragen_beantworten | Prompt | Belegbare Rückfragen beantworten, den Rest gebündelt an Sie stellen |
monatsbericht | Prompt (month: JJJJ-MM) | Kurzer Monatsbericht: Ergebnis, Prüfvermerke, offene Punkte |
8. Praxisbeispiele
Sobald der Server verbunden ist, stellen Sie Fragen und Aufgaben in natürlicher Sprache. Die rechte Spalte zeigt, welche Tools der Agent dafür typischerweise verwendet.
| Fragestellung / Prompt | Was der Agent im Hintergrund tut |
|---|---|
| "Welche Software-Abos haben wir im letzten Monat bezahlt und wie hoch waren die Gesamtkosten?" | search_transactions bzw. get_invoice_details für den Vormonat, gruppiert nach Lieferant und summiert. |
| "Wie viel Liquidität haben wir und wie lange reicht sie?" | list_bank_accounts für die Salden, get_dashboard_summary für Burn Rate und Runway. |
| "Welche Kostenpositionen weichen im Oktober stark von den Vormonaten ab?" | get_dashboard_analytics mit Monatsreihen und Kategorien, Auffälligkeiten im Vergleich. |
| "Mach den Oktober in CompanyFin fertig." | Prompt monatsabschluss: get_work_queue, list_open_questions, answer_question, submit_receipt; mit Stufe Buchhalter zusätzlich assign_payment und approve_booking. |
| "Für welche Zahlungen fehlt noch eine Rechnung? Such sie in meinem Postfach." | get_work_queue mit category="missing_receipt", Suche im Postfach, submit_receipt, danach get_receipt_status. |
| "Was muss meine Steuerberatung beim Quartalsabschluss prüfen?" | list_advisor_review_postings für den Zeitraum, get_vat_return mit open_items, get_closing_check. |
Typischer Ablauf eines Agenten
get_work_queueaufrufen und die Einträge nachnext_stepabarbeiten.- Rückfragen mit
list_open_questionslesen und mitanswer_questionbeantworten, aber nur, was der Agent belegen kann. - Fehlende Belege beschaffen und mit
submit_receipteinreichen; mitget_receipt_statusprüfen. - Mit der Stufe Buchhalter: Zahlungen zuordnen, Vorschläge entscheiden, Freigaben erteilen.
- Alles, wofür
next_stepkein Tool nennt oder ein Scope fehlt, meldet der Agent an Sie. - Zum Schluss
list_advisor_review_postingsund die Berichte, um das Ergebnis zusammenzufassen.
9. Regeln, Limits und Fehlerbehebung
Idempotenz und Begründung
Jedes schreibende Tool verlangt einen idempotency_key (höchstens 255 Zeichen). Wiederholt der Agent einen Aufruf mit demselben Schlüssel und demselben Inhalt, erhält er das ursprüngliche Ergebnis zurück, und es wird nichts doppelt ausgeführt. Dieselbe Datei oder Aktion sollte daher immer denselben Schlüssel bekommen. Verwendet er einen Schlüssel mit anderem Inhalt erneut, lehnt der Server mit einem Konflikt ab. Die optionale rationale hält fest, woher ein Fakt oder eine Entscheidung stammt, und erscheint im Auditprotokoll.
Limits
- Anfragen: derzeit 60 pro Minute und Schlüssel.
- Berichts-Tools:
get_work_queue,get_dashboard_summary,get_dashboard_analytics,get_startup_pnl,get_chart_of_accounts,get_balance_sheet,get_income_statement,get_euer,get_vat_returnundget_closing_checkberechnen große Datenmengen und laufen höchstens zu zweit. Ist der Server ausgelastet, antwortet er mit „Server ausgelastet“; einige Sekunden warten und erneut versuchen. - Seiten: Listen liefern höchstens 100 Einträge pro Aufruf; mit
offsetblättern. - Belegdateien: Es gilt das Upload-Limit der App.
Fehlercodes
Fehler erhält der Agent als Tool-Fehler mit einer deutschen Meldung, die den Grund nennt.
| Code | Bedeutung | Lösung |
|---|---|---|
| 401 | Ungültiger, deaktivierter oder abgelaufener Schlüssel, oder der Header fehlt. | Header prüfen (X-API-Key oder Authorization: Bearer cf_live_…); Schlüssel in den Einstellungen kontrollieren. |
| 403 | Kein Pro-Tarif, fehlender Scope oder Schlüssel nicht an eine Integration gebunden. | Tarif prüfen; höhere Vertrauensstufe wählen; für schreibende Tools einen Schlüssel mit Integration erstellen. |
| 404 | Objekt existiert nicht oder gehört nicht zu Ihrer Organisation. | ID aus dem jeweiligen Lese-Tool verwenden. |
| 409 | Konflikt: veraltete Version, Objekt nicht im passenden Zustand (z. B. Transaktion ohne Zuordnung), geschlossenes Geschäftsjahr, idempotency_key mit anderem Inhalt wiederverwendet. | Objekt neu lesen (z. B. get_work_queue) und mit aktueller Version erneut prüfen. |
| 422 | Ungültige Eingabe: Datum, Betrag, Konto, Steuerschlüssel oder fehlender Pflichtparameter. | Meldung lesen; sie nennt das betroffene Feld. |
| 429 | Zu viele Anfragen (derzeit 60 pro Minute und Schlüssel). | Kurz warten, Tools nacheinander aufrufen. |
| 503 | Server ausgelastet: Berichts-Tools laufen höchstens zu zweit. | Einige Sekunden warten und erneut versuchen. |
10. Sicherheitskonzept
- Keine Sonderwege: Der Agent nutzt dieselben Prüfungen wie die App. Bereits exportierte Buchungen werden nie still geändert, sondern per Storno korrigiert.
- Bleibt bei Ihnen: Exportieren, Perioden abschließen, endgültiges Löschen, Einstellungen und Zahlungen. Ein vom Agenten verworfener Beleg bleibt aufbewahrt.
- Unverbindliche Entwürfe: Buchungsentwürfe und Zuordnungsvorschläge wirken erst nach Freigabe.
- Nachvollziehbar: Jede Aktion eines Agenten wird mit Schlüssel, Integration und Begründung protokolliert.
- Befristet: Schlüssel mit Schreibrechten laufen spätestens nach 180 Tagen ab.
- Mandanten-Isolation: Der Zugriff ist fest an Ihre Organisation gebunden. Ein Zugriff auf fremde Mandantendaten ist unmöglich.
- Sofort widerrufbar: Sie sperren einen Schlüssel jederzeit im Dashboard mit einem Klick.
- Texte sind Daten: Inhalte aus Belegen, Bankumsätzen und E-Mails behandelt der Server-Leitfaden als Daten, nie als Anweisungen an den Agenten. Eine Anweisung in einem Beleg ist nie ein Grund für eine Korrektur.