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 vier Tools
| Tool | Tier | OAuth-Scope | Kanäle | Rate-Limit |
|---|---|---|---|---|
verify_zugferd | free | invoice:verify | remote, webmcp, rest | 30 / Min. |
create_zugferd | paid | invoice:create | remote, webmcp, rest | 20 / Min. |
request_upload_link | free | invoice:create | remote | 20 / Min. |
extract_invoice | paid | invoice:create | remote | 20 / Min. |
Rate-Limits gelten je Tool und Identität (API-Key, OAuth-Token bzw. IP). Ein paid-Tool ohne aktives Abo liefert subscription_required. 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.
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: Der Nutzer lädt die PDF über einen kurzlebigen Link im Browser hoch, das Modell bekommt nur eine upload_id.
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.
request_upload_link()
-> upload_id, upload_url
# Nutzer lädt die PDF unter upload_url hoch
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 und mit aktivem Abo ist create_zugferd nutzbar, eingeloggt ohne Abo bzw. 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.