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.

finisma in MCP-Verzeichnissen

Offizielle MCP Registry: de.finisma/finisma
Smithery: smithery.ai/servers/finisma/finisma

Maschinenlesbar

Clients und Verzeichnisse finden den Server ohne Handarbeit: die Server Card (SEP-2127) nennt Endpunkt, Protokollversionen und den optionalen Authorization-Header, der AI Catalog ist der Einstieg für Domain-Crawler, und server.json ist der Eintrag für die MCP Registry. Alle drei kommen aus einer Quelle und tragen dieselbe Version wie die Antwort auf initialize. Die vollständige Liste steht in llms.txt unter „Maschinenlesbare Dokumente“.

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.