Imported from domonda/api (mcp/claude-desktop/SKILL.md). Install upstream with npx skills add domonda/api --skill claude-desktop. Copyright stays with the author.

domonda MCP Skill

Connect to the domonda financial data platform via its MCP server. Query documents, invoices, payments, money transactions, companies, GL accounts, partner companies, and document workflows. All query tools are read-only; the only write tool is add_document, which uploads a file into the authenticated company's document pipeline.

Language note. The live MCP tool and parameter descriptions surfaced by the server are written in German, including a "Nutzen wenn …" block of trigger phrases. This matches the domonda-app UI and the natural vocabulary of end users, and improves discoverability for clients (e.g. ChatGPT) that match user prompts against tool descriptions by embedding similarity. The English descriptions in this file are developer-facing reference only — what your agent actually sees at runtime is the German text from the server.

If you are unsure which tool to call, call list_capabilities first to get a topic-grouped catalog of all available tools.

Agent Security Rules

• Never display, log, or transmit the API key in plain text.
• Never pass the API key as a CLI argument or embed it in URLs.
• Only use the API key for authenticating against the domonda MCP endpoint.
• Do not write, modify, or delete data via execute_query or any query tool — those tools are read-only and any DML will be rejected by the server.
• The only write tool is add_document. Only call it when the user has explicitly asked you to upload a document. Never call it on your own initiative, and never use it to write arbitrary data.

Quick Start

Pick one of:

a. Custom Connector UI (recommended, production, OAuth):

1. In Claude Desktop: Settings → Connectors → Add custom connector.
2. URL: https://domonda.app/api/mcp/
3. Complete the Auth0 OAuth prompt.

b. mcp-remote stdio bridge (localhost dev or raw JWT):

Edit claude_desktop_config.json and add:

{
  "mcpServers": {
    "domonda": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://domonda.app/api/mcp/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY_HERE"
      ]
    }
  }
}

Restart Claude Desktop afterwards. Verify endpoint connectivity with:

./scripts/health_check.sh

See README.md for when to choose which path.

Available Tools

The description paragraph for each tool below is written in German (matching what the running MCP server actually surfaces to clients), because domonda end users chat in German and tools are picked by similarity to the user's prompt. The parameter tables and technical notes stay in English.

Discovery

list_capabilities

Liefert einen nach Thema gruppierten Katalog ALLER verfügbaren Domonda-Tools mit einer kurzen deutschen Einzeiler-Beschreibung pro Tool. Dient als Einstiegspunkt: bei Unsicherheit, welches Tool passt, zuerst dieses aufrufen und dann das passende Tool direkt nutzen. Nutzen wenn der Benutzer nach "was kannst du", "welche Tools", "welche Werkzeuge", "hilf mir", "Übersicht", "Katalog", "was ist verfügbar", "Capabilities", "Hilfe" fragt.

Parameters: None

Schema Tools

list_tables

Listet alle Tabellen und Views im api-Schema der Domonda-Datenbank (Name, Typ Tabelle/View, Beschreibung). Nutzen für Datenmodell-Exploration, bevor eine benutzerdefinierte Abfrage via execute_query gebaut wird, oder wenn der Benutzer nach "welche Tabellen gibt es", "Datenmodell", "Schema", "was ist in der DB" fragt.

Parameters: None

describe_table

Beschreibt die Spalten einer Tabelle oder View im api-Schema: Spaltennamen, Datentypen, NULL-Zulässigkeit, Default-Werte. Nutzen bevor eine SELECT-Abfrage via execute_query geschrieben wird, um die verfügbaren Spalten zu kennen, oder wenn der Benutzer nach "welche Spalten", "Struktur der Tabelle", "Felder" fragt.

Query Tools

execute_query

Führt eine READ-ONLY SQL-Abfrage (SELECT oder WITH) gegen das api-Schema der Domonda-Datenbank aus. Nur das api-Schema ist zugänglich; pg_catalog, information_schema und andere Schemata werden abgelehnt. Unqualifizierte Tabellennamen werden ins api-Schema aufgelöst. Ergebnis: JSON-Array von Objekten, maximal 1000 Zeilen. Daten sind auf den angemeldeten Mandanten eingeschränkt, aber per-Benutzer-ACL wird NICHT angewendet — gibt Daten des gesamten Mandanten zurück. Deshalb nur für Admin-/Accountant-OAuth-Benutzer freigegeben; andere Benutzer und API-Key-Aufrufer erhalten einen Autorisierungsfehler. Für benutzergefilterte Listen stattdessen die spezialisierten Tools (list_documents, list_invoices, list_money_transactions, …) nutzen. Vorher list_tables und describe_table nutzen, um das Schema zu erkunden.

Access. This tool is company-scoped but does not apply per-user ACL, so it is restricted to admin, super-admin, or accountant OAuth users at the selected client company. API-key callers are rejected outright with Tool execute_query is not available to API-key callers.

Rejected before the query reaches the database. A query is refused when it does not start with SELECT or WITH, contains a DML/DDL keyword, references a schema other than api, uses a pg_* identifier outside the introspection allowlist, calls a mutating api function by name (update_document, create_invoice_accounting_item, partner_company_mutation, …), or uses Postgres Unicode-escape syntax (U&"…" / U&'…'). The identifier scans run against the raw SQL text, so a rejected name matches inside string literals and comments too — WHERE title ILIKE '%update_document%' fails. Use search_documents or the fulltext filter of list_documents for such text searches.

Document Tools

list_documents

Sucht, filtert und listet Dokumente des Mandanten: Rechnungen, Verträge, Belege, Lieferscheine, Kontoauszüge, sonstige Dokumente, DMS. Unterstützt Volltextsuche, Datumsbereiche (mehrere Datumstypen), Beträge, Zahl- und Exportstatus, Geschäftspartner, Kategorien, Dokumentarten, Genehmigungsstatus, Duplikate, Kommentare, Vertragstypen und konfigurierbare Sortierung. Nutzen wenn der Benutzer nach "Dokumente", "Belege", "Rechnungen", "Verträge", "Lieferscheine", "Kontoauszüge", "Mahnungen", "was liegt im Eingang", "Dokumentenliste", "welche Dokumente gibt es zu …", "suche Beleg über …", "offene Rechnungen", "nicht freigegebene", "nicht exportierte" fragt. Für reine Volltextsuche ohne Filter siehe search_documents.

All filter parameters are optional; omitting a parameter lets the server default apply.

The full enum values for export_status, paid_status, document_types, contract_type, and order_bys are exposed on the live tool schema — your MCP client will surface them.

get_document

Liefert Metadaten eines einzelnen Dokuments anhand seiner UUID: Dokumentart, Kategorie, Geschäftspartner, Datum, Status, Beträge (soweit vorhanden). Enthält nicht den Volltext — siehe get_document_fulltext für den extrahierten OCR-Text oder get_invoice für Rechnungs-Positionen. Nutzen wenn der Benutzer nach "Details zum Dokument", "Info zu diesem Beleg", "was ist das für ein Dokument", "wer hat das hochgeladen", "welche Kategorie" fragt.

get_document_fulltext

Liefert den extrahierten Volltext (OCR) eines Dokuments. Nutzen wenn der Benutzer den kompletten Inhalt eines Dokuments lesen will — "Volltext", "was steht im Beleg", "OCR-Text", "Inhalt dieses Dokuments".

Warning: fulltexts can be very large; long documents may approach or exceed the MCP response byte cap (default 10 MiB) and the call will fail. For pure search prefer search_documents and only fetch the fulltext of a specific hit when really needed.

search_documents

Volltextsuche über alle Dokumente des Mandanten; Treffer sind nach Relevanz sortiert. Nutzen wenn der Benutzer etwas FINDEN will, statt gezielt zu filtern — z. B. "finde Beleg über Büromöbel", "such mir alles zu Projekt X", "gibt es eine Rechnung mit …", "wo taucht der Begriff … auf". Für strukturierte Filter (Datum, Partner, Status, Beträge) lieber list_documents verwenden.

download_document_pdf

Lädt die Original-PDF-Datei eines Dokuments herunter — optional mit angehängtem oder vorangestelltem Audit-Trail (Protokoll der Bearbeitungsschritte, Freigaben, Änderungen). Standard: die PDF-Bytes werden base64-kodiert inline zurückgegeben. Mit inline: false wird stattdessen ein MCP resource_link auf document://{document_id}/pdf?... geliefert, den ein resource-fähiger Client via resources/read nachladen kann. Nutzen wenn der Benutzer "die PDF", "das Original", "den Beleg herunterladen", "Rechnung als PDF", "mit Audit-Trail" sagt.

The PDF is also exposed as an MCP resource at document://{document_id}/pdf{?audit_trail,audit_trail_lang}, so resource-aware clients can fetch it via resources/read. The configured audit-trail value is resolved to append/prepend before a resource link is returned, so resource URIs are deterministic and cacheable.

get_document_thumbnail

Liefert die kleine Miniaturansicht (JPEG, 256 px breit, Seitenverhältnis erhalten) eines Dokuments als base64-kodierten Blob. Auch als MCP-Ressource unter document://{document_id}/thumb_256x0.jpeg verfügbar. Nutzen wenn der Benutzer eine schnelle Vorschau, ein Miniaturbild oder ein "Icon" eines Dokuments sehen will. Für eine größere Vorschau siehe get_document_preview.

get_document_preview

Liefert die große Vorschau (JPEG, 964×1364) eines Dokuments als base64-kodierten Blob — das größte vorgerenderte Vorschaubild. Auch als MCP-Ressource unter document://{document_id}/preview.jpeg verfügbar. Nutzen wenn der Benutzer "zeig mir das Dokument", "Vorschau", "wie sieht der Beleg aus", "Bild des Dokuments" sagt. Für eine kleinere Miniaturansicht siehe get_document_thumbnail; für die Original-PDF siehe download_document_pdf.

add_document (write)

Lädt ein neues Dokument (Rechnung, Beleg, Vertrag, Lieferschein, sonstige Datei) für den angemeldeten Mandanten hoch. Dubletten-Erkennung und Kategorie-Zuweisung laufen automatisch. Nutzen wenn der Benutzer "Dokument hochladen", "Beleg importieren", "Rechnung hinzufügen", "upload", "neues Dokument", "Datei einspielen" sagt. Vorher list_document_categories aufrufen, um eine gültige category_id zu ermitteln.

Supported file types: PDF, PNG, JPEG, TIFF, XML, HTML, RTF, DOC, DOCX, ODT, XLS, XLSX, ODS. This is the only write operation on the MCP server; the file is processed through the same pipeline as the public upload endpoint. Returns the new document UUID on success.

Agent guidance: Only call add_document when the user has explicitly asked you to upload a file. Do not use it on your own initiative.

Invoice Tools

list_invoices

Listet Rechnungen des Mandanten (Eingangs- und Ausgangsrechnungen, inkl. Gutschriften) mit Rechnungsnummer, Rechnungsdatum, Fälligkeitsdatum, Geschäftspartner, Netto, Brutto, Währung, USt-Satz, Zahlstatus, offenem Betrag und Buchungsstatus. Filter: Datumsbereich, Partner-Name, Mindest-/Maximalbetrag. Nutzen wenn der Benutzer nach "Rechnungen", "Eingangsrechnungen", "Ausgangsrechnungen", "ER", "AR", "Gutschriften", "offene Posten", "Forderungen", "Verbindlichkeiten", "unbezahlte Rechnungen", "Rechnungen von " fragt. Für einzelne Rechnungsdetails siehe get_invoice.

get_invoice

Liefert alle Details zu einer einzelnen Rechnung: Kopfdaten, Positionen (Line Items), Skonto, Fälligkeit, umgerechnete EUR-Beträge, Geschäftspartner, UID/VAT-ID des Partners, zugeordnete Zahlungen. Nutzen wenn der Benutzer eine konkrete Rechnung im Detail sehen will — "zeig mir Rechnung …", "Details zu dieser Rechnung", "was steht auf der Rechnung", "Positionen", "Line Items", "Skonto", "Fälligkeit". Für eine Liste mehrerer Rechnungen siehe list_invoices.

Payment Tools

list_money_accounts

Listet alle Bankkonten und Zahlungskonten des Mandanten: Bankkonten, Kreditkarten, PayPal, Wise, Kassa. Nutzen wenn der Benutzer nach "Bankkonto", "Bankkonten", "Konten", "Kreditkarte", "PayPal", "Kassa", "welche Konten haben wir", "IBAN" fragt — oder wenn eine Kontoauswahl für weitere Filter benötigt wird.

Parameters: None

list_money_transactions

Listet Banktransaktionen und Kreditkartenbewegungen des Mandanten mit Betrag, Währung, Buchungsdatum, Valutadatum, Empfänger/Zahler, Verwendungszweck und Typ (EINGEHEND/AUSGEHEND). Filter: Konto, Typ, Datumsbereich, Partner-Name. Nutzen wenn der Benutzer nach "Transaktionen", "Banktransaktionen", "Buchungen auf dem Konto", "Kontoauszug", "Ein- und Ausgänge", "Zahlungseingang", "Zahlungsausgang", "Umsätze" fragt.

get_invoice_payments

Liefert alle Zahlungen (Banktransaktionen), die einer bestimmten Rechnung zugeordnet sind, inkl. offenem Betrag, bereits verrechneter Summe, Zahlstatus und Zahldatum. Nutzen wenn der Benutzer nach "Zahlungen zur Rechnung", "ist bezahlt", "offener Betrag", "welche Zahlung wurde zugeordnet", "Zahlungsabgleich", "Payment Matching" für eine konkrete Rechnung fragt.

Company Tools

get_my_company

Liefert die Stammdaten des eigenen Mandanten (angemeldete Firma): Firmenname, Rechtsform, Hauptsitz/Adresse, Telefon, E-Mail, Website, UID/VAT-Nummer, Steuernummer, Handelsregister-Nummer. Nutzen wenn der Benutzer nach "meine Firma", "mein Mandant", "unsere Firma", "Firmendaten", "Stammdaten", "UID", "VAT-ID", "Steuernummer", "Firmenadresse", "Hauptsitz", "wer sind wir" fragt.

Parameters: None

list_document_categories

Listet alle Dokumentenkategorien des Mandanten (visuelle Kategorien für die Ablage). Nutzen wenn der Benutzer nach "Kategorien", "Dokumentenkategorien", "Ablagekategorien", "welche Kategorien gibt es", "wo wird abgelegt" fragt oder bevor ein Dokument via add_document hochgeladen wird, um eine gültige category_id zu ermitteln.

Parameters: None

list_gl_accounts

Listet alle Sachkonten (GL accounts, Hauptbuchkonten) des Mandanten mit Nummer und Bezeichnung. Nutzen wenn der Benutzer nach "Sachkonto", "Sachkonten", "Kontenplan", "Buchungskonto", "GL account", "general ledger", "Hauptbuch", "Kontonummer" fragt — typischerweise für Buchhaltung, Kontierung und Accounting-Export.

Parameters: None

list_partner_companies

Listet Geschäftspartner des Mandanten: Kunden, Lieferanten, Debitoren, Kreditoren — mit Namen, abgeleitetem Namen, Debitoren- und Kreditoren-Kontonummer. Optional nach Namen filterbar. Nutzen wenn der Benutzer nach "Kunde", "Kunden", "Lieferant", "Lieferanten", "Geschäftspartner", "Partner", "Debitor", "Kreditor", "vendor", "supplier", "customer" fragt.

User Tools

get_user

Liefert den aktuell angemeldeten Benutzer (Name, E-Mail, Sprache, Mandant). Nutzen wenn der Benutzer nach "wer bin ich", "mein Profil", "mein Konto", "Benutzer", "User", "angemeldet" fragt oder wenn ein anderes Tool die aktuelle Benutzer-ID benötigt. Funktioniert nur bei OAuth-Login — API-Key-Zugriff liefert hier einen Fehler, weil der Key einen Mandanten identifiziert, keinen Benutzer.

Parameters: None

Workflow Tools

list_document_workflows

Listet alle im Mandanten konfigurierten Dokument-Workflows (Freigabe-Prozesse) mit Namen und IDs. Ein Workflow ist ein Ablauf, den ein Dokument durchläuft, bestehend aus mehreren Workflow-Schritten. Nutzen wenn der Benutzer nach "Workflows", "Freigabe-Prozess", "Genehmigungsprozess", "Approval-Flow", "welche Workflows gibt es" fragt. Für die einzelnen Schritte eines Workflows siehe list_document_workflow_steps.

list_document_workflow_steps

Listet Workflow-Schritte des Mandanten (einzelne Stationen eines Freigabe-Workflows). Ein Dokument steht zu jedem Zeitpunkt in genau einem Workflow-Schritt. Nutzen wenn der Benutzer nach "Workflow-Schritten", "Freigabeschritten", "Genehmigungsstufen", "welche Schritte hat unser Workflow", "Approval-Steps" fragt. Für den aktuellen Schritt konkreter Dokumente siehe list_document_workflow_states.

list_document_workflow_states

Liefert den AKTUELLEN Workflow-Zustand von Dokumenten: in welchem Workflow-Schritt steht ein Dokument gerade, und wie lautet sein Status. Eine Zeile pro Dokument. Nutzen wenn der Benutzer nach "Wo steht das Dokument gerade", "in welchem Schritt", "Freigabestatus", "wartet auf Freigabe von …", "welche Dokumente hängen wo", "Workflow-Status" fragt.

App URL Tools

get_app_urls

Liefert Deep-Links in die Domonda Web-App, zugeschnitten auf den angemeldeten Mandanten: Dokumente-Übersicht, Bank (Banking), Buchhaltungsansicht, Workflows/Freigaben, Academy (Hilfe/Doku), API-Repository. Nutzen wenn der Benutzer "öffne in Domonda", "zeig mir in der App", "Link zu …", "wo finde ich das", "geh in die Bank-Ansicht", "geh in die Buchhaltung" sagt.

• documents_overview — main documents list
• banking — banking overview
• accounting — documents list with accounting view
• workflows — documents list with workflow view (unapproved)
• documentation — user-facing documentation (academy)
• api — public API repository

Parameters: None

get_document_urls

Liefert Deep-Links in die Domonda Web-App für EIN einzelnes Dokument: Tabs Prüfung (review), Zahlung (payment), Buchhaltung (accounting) und Zusammenarbeit (collaboration). Nutzen wenn der Benutzer "öffne dieses Dokument in Domonda", "Link zum Beleg", "spring zu Zahlung/Buchhaltung/Prüfung" für ein konkretes Dokument sagt. Das Dokument muss zum angemeldeten Mandanten gehören.

get_document_selection_url

Liefert Deep-Links in die Domonda Web-App, die eine Auswahl MEHRERER Dokumente gemeinsam öffnen — je eine URL pro Mehrfach-Ansicht: thumb_view (Miniaturansicht), list_view (Listenansicht), accounting_view (Buchhaltungsansicht), workflow_view (Freigabenansicht). Nutzen wenn der Benutzer "öffne diese Rechnungen in Domonda", "zeig mir diese Belege in der App", "Link zu diesen Dokumenten", "Buchhaltungsansicht für diese Dokumente" sagt. Alle Dokumente müssen zum angemeldeten Mandanten gehören.

URLs use the ?documentRowIds[]=<uuid>&view=<VIEW> schema consumed by the domonda-app frontend routing; document ownership is verified per-id on the server.

Authentication

The domonda MCP server uses Bearer token authentication over Streamable HTTP. Two token types are accepted: a domonda API key (HS256 JWT, whose sub claim contains the client company ID) and an OAuth access token obtained by signing in with a domonda account. All queries execute within a read-only, company-scoped database transaction.

Pass the token in the HTTP Authorization header:

Authorization: Bearer <your-api-key-or-oauth-token>

An unauthenticated GET of the base URL answers 401 with a WWW-Authenticate header — that is the healthy response and it is what starts OAuth discovery, not an error to work around.

OAuth users must be an admin, super-admin, or accountant at the selected client company; every tool call from any other user is refused with Not allowed: MCP access is restricted to admin or accountant users. Beyond that gate, the single-document tools and the document resources enforce the OAuth user's own document read permission, and the money tools require the ViewMoneyAccounts / ViewMoneyTransactions role flags. An API key represents the whole tenant.

Usage Tips

• Start with get_my_company to confirm connectivity and see which company you are authenticated as.
• Use list_tables and describe_table for schema discovery before writing queries.
• Use execute_query for ad-hoc SQL queries when the specialized tools don't cover your use case — it needs an admin/accountant OAuth user and is not available to API-key callers.
• All date parameters use YYYY-MM-DD format.
• UUID parameters must be valid UUID strings.
• Results are capped at 1000 rows — use limit and offset for pagination.
• offset is clamped to 100,000; stream beyond that by narrowing filters (date range, partner, status) instead of paginating deeper.
• execute_query rejects SQL longer than 10,000 characters; any query result larger than 10 MiB is refused — narrow the query or select fewer columns.