MCP-Connector und WebMCP

Dieselbe Funktionsschicht wie die REST-API steht Claude, ChatGPT und anderen MCP-Clients als Remote-MCP-Server zur Verfügung, und den Browser-Agenten dieser Website zusätzlich als In-Page-Tools über WebMCP.

Remote-MCP-Server

URL https://finisma.de/api/mcp, Streamable-HTTP-Transport (jede Anfrage ein eigener JSON-RPC-Request, keine SSE-Session). Authentifizierung per API-Key oder OAuth 2.1 als Bearer-Token, genau wie bei der REST-API. Ohne Credential sind die free-Tools nutzbar, dann greift ein Rate-Limit nach IP statt nach Key.

Die sechs Tools

Tool	Tier	OAuth-Scope	Kanäle	Rate-Limit
`verify_zugferd`	free	`invoice:verify`	remote, webmcp, rest	30 / Min.
`create_zugferd`	freemium	`invoice:create`	remote, webmcp, rest	20 / Min.
`request_upload_link`	free	`invoice:create`	remote	20 / Min.
`extract_invoice`	paid	`invoice:create`	remote, rest	10 / Min.
`check_vat_id`	free	`invoice:verify`	remote, webmcp, rest	30 / Min.
`check_peppol_participant`	free	`invoice:verify`	remote, webmcp, rest	30 / Min.

Die beiden Partner-Checks sind der Preflight vor dem Rechnungsversand: check_vat_id fragt VIES live (Antwort-Status unavailable heißt "keine Aussage", nicht "ungültig"), check_peppol_participant schlägt per SML/SMP nach, ob der Partner im Peppol-Netz erreichbar ist — registered: false ist dabei ein normales Ergebnis, kein Fehler.

Rate-Limits gelten je Tool und Identität (API-Key, OAuth-Token bzw. IP). Ein paid-Tool ohne aktives Abo liefert subscription_required. create_zugferd ist freemium: ohne Abo zahlt zuerst das Guthaben (1 Credit je Rechnung, ohne Wasserzeichen und ohne Tageslimit), sonst kostenlos mit Konto — die PDF trägt dann das finisma-Prüfsiegel als Wasserzeichen, standardmäßig bis zu 5 Rechnungen pro Tag — danach free_quota_exhausted (HTTP 429, Retry-After bis Mitternacht). Ein fehlender OAuth-Scope liefert insufficient_scope, auch dann, wenn das Konto die Funktion an sich hätte. request_upload_link und extract_invoice teilen sich den Scope invoice:create: Beide sind Vorbereitungs- bzw. Korrekturschritte vor create_zugferd, kein eigenständiger Berechtigungskreis.

extract_invoice hat mit 10 Aufrufen pro Minute das strengste Rate-Limit, weil je Aufruf ein Sprachmodell läuft. Aus demselben Grund gilt das kostenlose Tageskontingent von create_zugferd hier nicht; ohne Abo kostet der Aufruf 1 Credit. Über HTTP steht dieselbe Funktion als POST /api/v1/extractions bereit, für Integrationen, die keinen MCP-Client bauen wollen.

verify_zugferd prüft eine ZUGFeRD-/Factur-X-PDF (Struktur, EN-16931-Regeln, PDF/A-3-Anhänge) und funktioniert ohne Credential. create_zugferd nimmt die visuelle Rechnungs-PDF und die strukturierten EN-16931-Daten entgegen und erzeugt deterministisch (kein Sprachmodell) das CII-XML samt PDF/A-3-Einbettung.

Korrekturschleife für Chat-Clients

Angehängte Dateien kann ein Chat-Modell oft nicht zuverlässig als Base64 an ein Tool übergeben; dafür gibt es request_upload_link. Zwei Wege: Der Nutzer lädt die PDF über upload_url im Browser hoch, ODER der Agent mit Shell und Netzzugriff lädt sie selbst hoch, per POST als Multipart-Feld file an upload_api_url aus derselben Antwort (nur echte PDFs, max. 25 MB, der Slot verfällt nach 20 Minuten). Für den Direktweg muss finisma.de erreichbar sein; in Claude-Umgebungen mit Netz-Sandbox heißt das, die Domain in die Domain-Allowlist der Umgebung aufzunehmen. Das Modell arbeitet danach in beiden Fällen nur mit der kurzen upload_id.

curl -sS -X POST -F "file=@rechnung.pdf;type=application/pdf" <upload_api_url>
# Antwort: {"ok":true} — danach upload_id wie gewohnt verwenden

Für den Prüf- und Korrekturschritt im Chat gibt es extract_invoice: Es nimmt eine upload_id (oder pdf_base64) entgegen, liest die Rechnung mit derselben Extraktions-Pipeline wie das Web-Formular aus und liefert die Rechnungsdaten (invoice) plus eine Liste offener Probleme (validation_issues) zurück. Konnte ein Feld nicht sicher gelesen werden, steht dort der Platzhalter "KORRIGIEREN" (Text) bzw. "1900-01-01" (Datum), beide werden als Issue mit Code EXTRACTION_UNCERTAIN gemeldet.

Der Chat zeigt Felder und Issues, lässt sie korrigieren und ruft dann create_zugferd mit derselben upload_id und dem korrigierten invoice auf. Verletzen die Daten weiterhin EN-16931-Geschäftsregeln, erzeugt create_zugferd auf diesem Kanal keine Datei, sondern liefert dieselbe Issues-Struktur zurück, damit der Chat die Schleife wiederholen kann. Ohne invoice bzw. ohne Fehler verhält sich create_zugferd wie gewohnt.

Die invoice-Struktur ist auf allen Kanälen dieselbe wie in der REST-API, einschließlich der Kopf-Felder für Bau- und Projektrechnungen (Projekt- und Vertragsnummer, Leistungszeitraum, Nachlässe, abweichender Zahlungsempfänger). Das Tool-Schema liefert der Connector selbst mit; ein vollständiges Beispiel zeigt die REST-Referenz, Beispiel 3.

request_upload_link()
  -> upload_id, upload_url, upload_api_url, expires_at

# Nutzer lädt die PDF unter upload_url hoch
# ODER der Agent selbst: curl -F "file=@rechnung.pdf" <upload_api_url>

extract_invoice({ upload_id })
  -> invoice, validation_issues, upload_id, expires_at

# Nutzer korrigiert die von validation_issues markierten Felder

create_zugferd({ upload_id, invoice: <korrigiert> })
  -> download_url   ODER   issues (bei weiterhin offenen Fehlern)

WebMCP

Zusätzlich zum Remote-Server deklariert finisma.de seine Tools direkt in der Seite über die entstehende Web-Model-Context-API (document.modelContext). Ein Agent, der im Browser auf finisma.de operiert, ruft die Tools damit unmittelbar in der laufenden Seite auf, ganz ohne API-Key und ohne den Umweg über den Remote-Server.

Entitlement ist hier nicht der Scope eines Tokens, sondern die normale Login-Session im Browser: eingeloggt mit aktivem Abo ist create_zugferd ohne Einschränkung nutzbar, eingeloggt ohne Abo zuerst gegen Guthaben (1 Credit je Rechnung), sonst mit Wasserzeichen und Tageskontingent, anonym bleibt verify_zugferd. Verfügbar über diesen Kanal sind ausschließlich diese beiden Tools. request_upload_link und extract_invoice sind reine Remote-Kanal-Werkzeuge, im Browser hat der Agent die Datei ohnehin schon.

Die Ausführung läuft über POST /api/capabilities/{id} mit der Session als Cookie; das maschinenlesbare Tool-Verzeichnis für diesen Kanal (Beschreibung, JSON-Schemas, aktueller Login- und Abo-Status) liefert GET https://finisma.de/api/capabilities. Dort stehen auch beide MCP-Server (remote und webmcp) mit ihrer Tool-Liste zur Selbst-Discovery für Agenten und Integratoren.

Technisch registriert die Seite die Tools über das Polyfill @mcp-b/global, das eine native Browser-Implementierung nutzt, sobald ein Browser sie mitbringt, und sonst über eigene Bridge-Transports funktioniert. Für Entwickler bedeutet das: sobald document.modelContext existiert (nativ oder per Polyfill), sind die Tools auf jeder Seite von finisma.de registriert, nicht nur auf einer bestimmten Unterseite.

Vollständiges Aufruf-Beispiel und Hintergrund zu MCP: E-Rechnung per API und KI-Agent erstellen. REST-Referenz für Server-zu-Server-Integrationen ohne Chat-Client: REST-API-Referenz.