Buchhaltung mit Codex: OpenAI Codex per MCP-Server verbinden

Wo Codex läuft und was es mit Ihrer Buchhaltung kann

Codex ist der Agent von OpenAI für die Kommandozeile, die Entwicklungsumgebung und die Desktop-App. Für die Buchhaltung ist entscheidend, dass Codex einen entfernten MCP-Server über Streamable HTTP mit einer eigenen Kopfzeile anspricht:

Schritt 1: Schlüssel anlegen und als Umgebungsvariable setzen

• In der App unter Buchhaltung → Einstellungen → „KI-Agent & API“ legen Administratoren oder der Ersteller des Arbeitsbereichs einen Schlüssel an und bestätigen mit dem zweiten Faktor.
• Rechte: read ist immer enthalten. write erlaubt Buchen, Stornieren, Rechnungen, Zahlungen, Belege, Bank und Stammdaten sowie die amtliche Steuerprüfung und das Vorbereiten einer Übermittlung; send erlaubt den Rechnungsversand an hinterlegte Adressen, finalize das Festschreiben. Für den Anfang genügt read.
• Als Laufzeit bietet die App 30 Tage, 90 Tage oder ein Jahr an; für einen ersten Versuch mit Codex genügen 30 Tage. Der Schlüssel beginnt mit jab_live_, erscheint nur einmal und öffnet genau eine Gesellschaft.
• Setzen Sie ihn in Ihrer Shell, etwa mit export JAB_API_KEY="jab_live_…" in ~/.zshrc. Für eine zweite Gesellschaft nehmen Sie eine zweite Variable und einen zweiten Eintrag, etwa [mcp_servers.buchhaltung_holding].

Schritt 2: den Server in config.toml eintragen

Die Felder url und bearer_token_env_var beschreibt OpenAI für Streamable-HTTP-Server; default_tools_approval_mode und tool_timeout_sec sind optional. So sieht der Eintrag für die Buchhaltung aus:

# ~/.codex/config.toml
[mcp_servers.buchhaltung]
url = "https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp"
bearer_token_env_var = "JAB_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 120

# Den Schlüssel nicht in diese Datei schreiben, sondern als Umgebungsvariable,
# z. B. in ~/.zshrc oder ~/.bashrc:
# export JAB_API_KEY="jab_live_…"

tool_timeout_sec hebt die Standardzeit je Werkzeugaufruf von 60 auf 120 Sekunden an; das hilft bei großen Exporten oder einer amtlichen Prüfung. Mit enabled_tools und disabled_tools können Sie die Werkzeugliste in Codex zusätzlich einschränken. Die harte Grenze ist aber das Recht des Schlüssels: Ein Leseschlüssel bekommt von unserem Server gar keine schreibenden Werkzeuge angeboten.

Eine projektbezogene .codex/config.toml lädt Codex nur in Projekten, denen Sie vertrauen. Für die Buchhaltung ist die Benutzerdatei ~/.codex/config.toml der richtige Ort, weil der Zugang zu einer Gesellschaft gehört und nicht zu einem Code-Projekt.

Alternativ per Befehl – und prüfen, ob die Verbindung steht

codex mcp add legt denselben Eintrag an. Einen Schalter für beliebige Kopfzeilen hat der Befehl nicht; für den Bearer-Schlüssel genügt --bearer-token-env-var:

# derselbe Server per Befehl (schreibt in ~/.codex/config.toml)
codex mcp add buchhaltung \
  --url https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp \
  --bearer-token-env-var JAB_API_KEY

# prüfen
codex mcp list
codex mcp get buchhaltung --json

# in einer laufenden Codex-Sitzung
/mcp

/mcp zeigt in der Sitzung die verbundenen Server und ihre Werkzeuge, /mcp verbose zusätzlich Diagnosedaten. Stehen dort nur lesende Werkzeuge, ist der Schlüssel ein Leseschlüssel – das ist für den Anfang so gewollt.

Meldet unser Server 401, ist die Variable leer, der Schlüssel abgelaufen oder widerrufen. Funktioniert es in der Kommandozeile, aber nicht in der Desktop-App oder der IDE-Erweiterung, fehlt dort meist die Umgebungsvariable: OpenAI weist darauf hin, dass Desktop-Apps und IDE-Erweiterungen Variablen aus der Shell nicht unbedingt erben, und nennt dafür die Datei ~/.codex/.env.

Freigaben und Sandbox von Codex – zwei verschiedene Dinge

• default_tools_approval_mode gilt für die MCP-Werkzeuge dieses Servers. Mit writes fragt Codex bei jedem Werkzeug, das nicht als lesend markiert ist. Je Werkzeug lässt sich das unter [mcp_servers.buchhaltung.tools.<werkzeug>] mit approval_mode überschreiben – heben Sie dort nichts Schreibendes auf „ohne Rückfrage“.
• Die Sandbox von Codex (sandbox_mode) begrenzt Befehle, die Codex auf Ihrem Rechner ausführt, etwa ein Skript oder curl. Sie ist nicht die Sandbox unserer Buchhaltung.
• Unsere Sandbox ist ein Zwilling Ihrer Gesellschaft, den Sie in den Einstellungen einrichten, mit eigenen Schlüsseln – derzeit für Gesellschaften ohne Jahresabschluss-Daten. get_entity meldet dann sandbox: true; gebucht wird nur im Zwilling, Versand und Übermittlung sind gesperrt. Ideal, um einen neuen Ablauf mit Codex auszuprobieren.
• Unabhängig von Codex weist unser Server den Agenten an, vor Ausstellen und Versand einer Rechnung, vor dem Storno einer Ausgangsrechnung, dem Löschen eines Belegs und dem Festschreiben Ihre ausdrückliche Bestätigung einzuholen – für jeden Vorgang einzeln.

Aufträge an Codex: Monatsabschluss und Umsatzsteuer

Codex eignet sich für Aufträge, die mehrere Abfragen verbinden. Beispiele mit den Werkzeugen, die der Agent aufruft:

Codex nach dem Ende eigener GPTs

OpenAI stellt eigene GPTs (Custom GPTs) laut eigener Ankündigung zum 11.12.2026 ein; eigene Actions werden dabei nicht übernommen. Wer seine Buchhaltung bisher über einen GPT mit unserer REST-API angesprochen hat, braucht danach einen anderen Weg bei OpenAI.

Codex ist dieser Weg: Es sendet einen festen Schlüssel als Kopfzeile und erreicht damit genau eine Gesellschaft. Eigene MCP-Server in ChatGPT im Browser melden sich derzeit nur per OAuth an; einen eigenen Schlüssel kann ChatGPT dort nicht senden, und OAuth bietet unser MCP-Server derzeit nicht an.

Grenzen und was in der App bleibt

• An ELSTER übermittelt wird in der App: Der Agent prüft amtlich, bereitet vor und gibt Ihnen den Freigabe-Link. Ein Recht, mit dem er selbst übermittelt, vergeben wir derzeit nicht.
• Was Codex auch mit write nicht erreicht: die Bankanbindung selbst, die Einstellungen der Gesellschaft, IBAN und BIC Ihrer Geschäftspartner und jede freie Datenbankabfrage – Codex arbeitet nur mit den dokumentierten Werkzeugen.
• Jede Buchung läuft durch denselben Buchungskern wie in der App: Soll gleich Haben, Storno statt Löschen, nichts in festgeschriebenen Zeiträumen. So bleibt nach § 146 Abs. 4 AO und § 239 Abs. 3 HGB der ursprüngliche Inhalt jeder Buchung feststellbar.
• 120 Anfragen pro Minute je Schlüssel; darüber antwortet die API mit 429 und Retry-After. Wiederholt Codex nach einer Zeitüberschreitung mit derselben UUID (idempotency_key), entsteht keine zweite Buchung.
• Was Codex vorschlägt, bleibt ein Vorschlag. Die Software ersetzt keine Steuerberatung; Ihre Kanzlei kann in derselben Software mitarbeiten und sieht dieselben Zahlen.

Häufige Fragen

Wie verbinde ich Codex mit meiner Buchhaltung?

Mit einem Eintrag [mcp_servers.buchhaltung] in ~/.codex/config.toml: url mit der Adresse unseres MCP-Servers und bearer_token_env_var mit dem Namen der Umgebungsvariable, in der Ihr Schlüssel steht. Alternativ legt codex mcp add buchhaltung --url … --bearer-token-env-var JAB_API_KEY denselben Eintrag an.

Gilt die Einrichtung auch für die Codex-Erweiterung und die Desktop-App?

Ja. Laut OpenAI teilen die Codex CLI, die IDE-Erweiterung und die ChatGPT-Desktop-App dieselbe Konfiguration. Achten Sie darauf, dass die Umgebungsvariable mit dem Schlüssel auch dort ankommt, wo die App startet.

Fragt Codex, bevor es bucht?

Mit default_tools_approval_mode = "writes" ja: Codex fragt bei jedem Werkzeug, das nicht als lesend markiert ist. Zusätzlich weist unser Server den Agenten an, vor Rechnungsversand, Storno einer Ausgangsrechnung, Beleglöschung und Festschreibung Ihre ausdrückliche Bestätigung einzuholen.

Kann Codex meine Umsatzsteuer-Voranmeldung abgeben?

Nein. Codex kann sie lesen, amtlich prüfen lassen, die Übermittlung vorbereiten und einen Freigabe-Link anfordern. Übermittelt wird in der App mit Ihrer PIN; die PIN gehört nie in den Chat.

Was ändert das Ende der eigenen GPTs am 11.12.2026 für mich?

Ein GPT mit Actions gegen unsere REST-API funktioniert danach nicht mehr, Ihre Buchungen bleiben unberührt. Für den Zugriff mit OpenAI richten Sie Codex mit dem MCP-Server ein; ChatGPT im Browser kann derzeit keinen eigenen Schlüssel an einen MCP-Server senden.

Brauche ich für Codex ein anderes Abo bei jahresabschluss.io?

Nein. Schlüssel gibt es ohne Aufpreis zum Buchhaltungs-Abo (Solo oder Gesamtpaket) und zum EÜR-Abo. Mit dem kostenlosen Steuer-Modul allein erreicht ein Schlüssel nur die Steuer-Werkzeuge und die Stammdaten.