CompanyFin MCP-Server: Einrichtung und Tool-Referenz

Verbinden Sie Ihren eigenen KI-Agenten über das Model Context Protocol (MCP) mit CompanyFin: Finanzfragen stellen, offene Punkte abarbeiten und Belege einreichen. Diese Seite zeigt die Einrichtung Schritt für Schritt und beschreibt jedes Tool des Servers. Für eigene Systeme und Skripte gibt es die separate REST-API-Dokumentation.

Das Wichtigste in Kürze
CompanyFin stellt einen Remote-MCP-Server bereit (Streamable HTTP): https://app.companyfin.de/api/v2/mcp/. Eine lokale Installation ist nicht nötig.
Die Anmeldung erfolgt mit einem API-Schlüssel im Header X-API-Key (oder Authorization: Bearer). Den Schlüssel erstellen Sie im Pro-Tarif unter Einstellungen → API und MCP.
35 Tools in drei Vertrauensstufen: Lesen (17 Tools), Zuarbeiten (9) und Buchhalter (9). Schreibende Tools brauchen eine Integration, ein Ablaufdatum und einen idempotency_key.
Der Agent bucht Regelfälle nicht selbst: CompanyFin bucht stimmige Belege automatisch, der Agent erledigt den Teil, der sonst bei Ihnen liegt.
Exportieren, Perioden abschließen, endgültiges Löschen, Einstellungen und Zahlungen kann kein Agent. Korrekturen laufen nur per Storno, Belege bleiben aufbewahrt.

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.

  1. Einstellungen öffnen: Melden Sie sich unter app.companyfin.de an und öffnen Sie Einstellungen → API und MCP.
  2. Nur lesen? Dann direkt weiter mit Schritt 4. Ein Schlüssel der Stufe Lesen braucht keine Integration.
  3. 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.
  4. 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).
  5. 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

Server-URL
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:

Terminal
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:

.mcp.json (Projekt)
{
  "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

mcp.json
{
  "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:

claude_desktop_config.json
{
  "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

  1. Fragen Sie Ihren Agenten: „Was ist in CompanyFin gerade offen?“ Er sollte get_work_queue aufrufen und die Arbeitsliste zusammenfassen.
  2. Antwortet er mit einem Authentifizierungsfehler, prüfen Sie Header und Schlüssel. Die häufigsten Ursachen stehen in Abschnitt 9.
  3. 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.

VertrauensstufeWas der Agent darf
Lesen (Standard)Kennzahlen, Umsätze, Belege, Arbeitsliste und Berichte abfragen. Keine Änderungen.
ZuarbeitenZusä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.
BuchhalterZusä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

ScopeBerechtigt zuEnthalten in
read:mcpMCP-Discovery: Voraussetzung für jeden MCP-ZugriffLesen
read:kpis, read:analyticsKennzahlen und AnalysenLesen
read:transactions, read:accountsBanktransaktionen, Bankkonten, KontenplanLesen
read:receiptsBelege, Arbeitsliste, Rückfragen, BelegstatusLesen
read:reportsBilanz, GuV, EÜR, Umsatzsteuer-Voranmeldung, PrüfvermerkeLesen
read:booking-drafts, write:booking-draftsEigene Buchungsentwürfe lesen, erstellen, ändern, verwerfenZuarbeiten
read:match-proposals, write:match-proposalsEigene ZuordnungsvorschlägeZuarbeiten
write:receipt-inboxBelege einreichen (werden automatisch verarbeitet)Zuarbeiten
write:clarification-answersRückfragen beantwortenZuarbeiten
write:match-assignmentsZahlungen zuordnen, Vorschläge annehmen oder ablehnenBuchhalter
write:booking-approvalsBuchungsvorschläge freigebenBuchhalter
write:receipt-decisionsDuplikate als eigenen Beleg bestätigenBuchhalter
write:match-correctionsFalsche Zuordnungen lösenBuchhalter
write:booking-correctionsPer Storno korrigieren, Beleg verwerfenBuchhalter
write:receiptsKategorie-Vorschläge für Belegpositionennur 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 Belegs
  • limit: 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: Textsuche
  • start_date, end_date: optional: Buchungsdatum von/bis
  • min_amount, max_amount: optional: Betragsspanne
  • limit, 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 Beleg
  • query: optional: Textsuche
  • start_date, end_date: optional: Belegdatum von/bis
  • min_amount, max_amount: optional: Bruttobetrag von/bis
  • receipt_type: optional: z. B. incoming, outgoing, other
  • ocr_status, match_status: optional: Filter nach Verarbeitungs- bzw. Zuordnungsstatus
  • vendor_name, invoice_number: optional: enthält-Filter
  • limit, offset: optional: Standard 25 (höchstens 100) und 0
  • include_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: Kalenderjahr
  • period: 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 Endung
  • idempotency_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_questions
  • value: Pflicht: Objekt nach value_format, z. B. {"choice": "business_only"} oder {"date": "2026-10-01"}
  • idempotency_key: Pflicht
  • rationale: 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 Entwurfs
  • payload: Pflicht: expected_version plus mindestens eines von booking_date, description, lines
  • idempotency_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 Entwurfs
  • payload: 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 optional
  • idempotency_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 Transaktion
  • receipt_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 Vorschlags
  • decision: Pflicht: accept oder reject
  • reason: nur bei reject: wrong_amount, wrong_partner, wrong_date, bulk_payment, partial_payment, wrong_receipt_type, duplicate oder other
  • idempotency_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 Buchungspakets
  • expected_version: Pflicht: aktuelle Version des Pakets
  • idempotency_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 Belegs
  • idempotency_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 Transaktion
  • reason: Pflicht: wrong_amount, wrong_partner, wrong_date, bulk_payment, partial_payment, wrong_receipt_type, duplicate oder other
  • idempotency_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 Belegs
  • preview_token: Pflicht: Token aus preview_booking_correction
  • reason_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 Buchungspakets
  • reason_code: Pflicht: incorrect_entry oder duplicate_entry
  • idempotency_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 Belegs
  • idempotency_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.

payload für create_booking_draft (Beispielwerte)
{
  "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_id und credit_account_id sind die id-Werte aus get_chart_of_accounts, nicht die Kontonummern.
  • description soll sagen, was gebucht wird und auf welcher Grundlage. Sie bleibt im Auditprotokoll.
  • Optional: receipt_id oder transaction_id verknü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_draft korrigieren.
tax_keyBedeutungBetrag / tax_amount
ohneKeine Umsatzsteuertax_amount 0
VSt19, VSt7Vorsteuer 19 % bzw. 7 %Betrag brutto, tax_amount = enthaltene Steuer
USt19, USt7Umsatzsteuer 19 % bzw. 7 %Betrag brutto, tax_amount = enthaltene Steuer
RC19, RC7Steuerschuld des Leistungsempfängers, § 13b UStG (Lieferant aus der EU)Betrag netto, tax_amount = geschuldete Steuer
RC19D§ 13b UStG, Lieferant aus einem DrittlandBetrag netto, tax_amount = geschuldete Steuer
IGE19, IGE7Innergemeinschaftlicher ErwerbBetrag 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.

NameArtInhalt
companyfin://guide/agent-workflowRessourceArbeitsablauf, Regeln und Sonderfälle für den Agenten
companyfin://guide/trust-levelsRessourceVertrauensstufen und deren Scopes
monatsabschlussPrompt (month: JJJJ-MM)Einen Monat fertigstellen: Arbeitsliste, Rückfragen, fehlende Belege, Zuordnungen, Bericht
belege_nachreichenPromptZahlungen ohne Beleg finden und die Rechnungen einreichen
rueckfragen_beantwortenPromptBelegbare Rückfragen beantworten, den Rest gebündelt an Sie stellen
monatsberichtPrompt (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 / PromptWas 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

  1. get_work_queue aufrufen und die Einträge nach next_step abarbeiten.
  2. Rückfragen mit list_open_questions lesen und mit answer_question beantworten, aber nur, was der Agent belegen kann.
  3. Fehlende Belege beschaffen und mit submit_receipt einreichen; mit get_receipt_status prüfen.
  4. Mit der Stufe Buchhalter: Zahlungen zuordnen, Vorschläge entscheiden, Freigaben erteilen.
  5. Alles, wofür next_step kein Tool nennt oder ein Scope fehlt, meldet der Agent an Sie.
  6. Zum Schluss list_advisor_review_postings und 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_return und get_closing_check berechnen 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 offset blä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.

CodeBedeutungLösung
401Ungü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.
403Kein 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.
404Objekt existiert nicht oder gehört nicht zu Ihrer Organisation.ID aus dem jeweiligen Lese-Tool verwenden.
409Konflikt: 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.
422Ungültige Eingabe: Datum, Betrag, Konto, Steuerschlüssel oder fehlender Pflichtparameter.Meldung lesen; sie nennt das betroffene Feld.
429Zu viele Anfragen (derzeit 60 pro Minute und Schlüssel).Kurz warten, Tools nacheinander aufrufen.
503Server 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.

Fachlich geprüft durch die CompanyFin Finanzredaktion

Dieser Beitrag wurde nach den aktuellen Vorgaben des Handelsgesetzbuchs (HGB), der Abgabenordnung (AO) und den GoBD redaktionell und steuerfachlich verfasst. Letzte redaktionelle Prüfung: 18. November 2026.

Häufig gestellte Fragen (FAQ)

Jeder Client, der Remote-MCP über Streamable HTTP (oder das ältere SSE) unterstützt und einen eigenen HTTP-Header senden kann, zum Beispiel Claude Code, Cursor, Zed und viele Agenten-Frameworks. Claude Desktop verbindet sich über den Adapter mcp-remote. Die Anmeldung erfolgt ausschließlich über einen API-Schlüssel, nicht über einen OAuth-Login.

Ein neuer Schlüssel ist standardmäßig nur lesend. Schreibrechte vergeben Sie bewusst als Vertrauensstufe: Mit „Zuarbeiten“ kann der Agent Belege einreichen, Rückfragen beantworten und unverbindliche Entwürfe anlegen, mit „Buchhalter“ zusätzlich Zahlungen zuordnen, Buchungsvorschläge freigeben und gebuchte Belege per Storno korrigieren. Dabei gelten dieselben Prüfungen wie in der App, und jede Aktion wird mit Herkunft und Begründung protokolliert. Exportieren, Perioden abschließen, endgültiges Löschen und Zahlungen auslösen kann kein Agent.

Regelfälle nicht. Stimmige Belege bucht CompanyFin automatisch, Unsicherheiten werden als Prüfvermerk für Ihre Steuerberatung gespeichert. Der Agent liefert, was sonst Sie liefern würden: fehlende Belege, Antworten auf Rückfragen und, mit der Stufe Buchhalter, Zuordnungen und Freigaben. Sonderfälle wie Rückstellungen oder Steuer nach § 13b UStG kann er als freie Buchung entwerfen; sie wird erst mit Freigabe wirksam und trägt einen Prüfvermerk.

Schreibende Tools brauchen einen Schlüssel mit passender Vertrauensstufe, der an eine Integration gebunden ist und ein Ablaufdatum von höchstens 180 Tagen hat. Fehlt das, antwortet der Server mit einem Tool-Fehler (403) und nennt den Grund. Prüfen Sie die Stufe unter Einstellungen → API und MCP.

Die MCP-Schnittstelle ist in allen Pro- und Enterprise-Plänen von CompanyFin ohne zusätzliche Gebühr enthalten. In der Testphase ist sie nicht verfügbar.

Buchhaltung ohne Frust und Medienbrüche

CompanyFin verknüpft Bankkonten, Beleg-OCR und den SKR04-Kontenrahmen. Erzeugen Sie fertige DATEV-Stapel mit Belegbildern auf Knopfdruck.

Passende Ratgeber & Dokumentationen