MCP-Konnektor

Paperarchive stellt einen Remote-Server für das Model Context Protocol (MCP) bereit. Einmal verbunden, kann ein KI-Assistent wie Claude, ChatGPT oder Grok dein Archiv durchsuchen, Dokumentdetails lesen, Kontoauszug-Transaktionen nachschlagen und dir Download-Links geben - direkt aus einer Unterhaltung heraus. Wenn du es erlaubst, kann der Assistent außerdem Rechnungen als bezahlt markieren, andere Ereignisse erledigen und Tags hinzufügen oder entfernen.

Endpunkt

https://api.paperarchive.io/mcp

Der Server spricht MCP über Streamable HTTP und authentifiziert über OAuth 2.1. Jeder MCP-Client mit Unterstützung für Remote-Server und OAuth kann sich verbinden. Die Autorisierung passiert in der Paperarchive-App: Du meldest dich an, prüfst die angefragten Berechtigungen, wählst die Spaces aus, auf die die Verbindung zugreifen darf, und bestätigst. Standardmäßig ist die Verbindung schreibgeschützt. Änderungen (Ereignisse erledigen, Dokumente taggen) sind eigene Berechtigungen, die aus bleiben, bis du sie auf der Freigabeseite einschaltest. Hochladen, Löschen oder Neuverarbeiten von Dokumenten ist über MCP nie möglich.

Voraussetzungen

Ein Paperarchive-Konto mit aktivem Premium- oder Testzeitraum (gleiche Voraussetzung wie bei API-Keys).
Ein MCP-Client mit Unterstützung für Remote-Server, zum Beispiel Claude, ChatGPT oder Grok (siehe die Einrichtungsanleitungen unten).

Verfügbare Tools

Tool	Scope	Beschreibung
`search_documents`	`search`	Volltextsuche über Titel, Absender, Kategorien, Tags und OCR-Text.
`list_documents`	`documents:read`	Dokumente durchblättern mit Filtern (Space, Kategorie, Status, Datum) und Paginierung.
`get_document`	`documents:read`	Dokumentdetails inkl. extrahierter Felder, Tags und optional OCR-Text.
`get_document_download_link`	`documents:read`	Kurzlebige signierte URL (10 Minuten) für die Originaldatei.
`list_statements`	`documents:read`	Kontoauszüge mit extrahierten strukturierten Daten.
`get_statement_transactions`	`documents:read`	Transaktionen, Salden, IBAN und Zeitraum eines Kontoauszugs.
`list_events`	`events:read`	Ereignisse (Rechnungen, Verträge, Policen, ...) mit Status, Betrag und Fälligkeit - beantwortet Fragen wie "Was ist offen oder fällig?".
`get_event`	`events:read`	Details eines Ereignisses inkl. Beträgen, Fristen, Referenznummer und Quelldokument.
`list_spaces`	`spaces:read`	Spaces, auf die die Verbindung zugreifen kann.
`list_categories`	`categories:read`	Kategorien zum Filtern von Dokumenten.
`list_tags`	`tags:read`	Tags in den zugänglichen Spaces.
`list_senders`	`senders:read`	Erkannte Absender in den zugänglichen Spaces.
`resolve_event`	`events:write`	Optional. Ein Ereignis erledigen: `paid`, `confirm`, `archive` oder `cancel` (dieselben Regeln wie in der App).
`add_document_tags`	`document_tags:write`	Optional. Vorhandene Tags (IDs aus `list_tags`) zu einem Dokument hinzufügen.
`remove_document_tags`	`document_tags:write`	Optional. Tags von einem Dokument entfernen; Paperarchive fügt sie nicht automatisch wieder hinzu.

Im Rollout (noch nicht für jedes Konto verfügbar) bekommen Konten mit den Erledigen-Funktionen zusätzlich diese Tools:

Tool	Scope	Beschreibung
`get_week_ahead`	`events:read`	Die höchstens drei dringendsten Punkte der Woche, jeder mit seiner Entscheidung.
`list_gaps`	`documents:read`	Offene Fragen zu erwarteten Dokumenten (Kontobewegung ohne Beleg, Unterlage für einen Antrag).
`get_property_overview`	`documents:read`	Vermietete Immobilie: Miete, nächste mögliche Erhöhung, Frist der Nebenkostenabrechnung (übliche Regeln, keine Rechtsberatung).
`get_investments`	`documents:read`	Depots aus den Depotauszügen: Wert, Gewinn, Rendite pro Jahr, mit Id die Positionen und Zahlungen (keine Kurse aus dem Internet, keine Anlageberatung).
`get_retention_expired`	`documents:read`	Dokumente privater Spaces, deren übliche Aufbewahrungsfrist abgelaufen ist; gelöscht wird nichts.
`get_health_overview`	`health:read`	Optional, Gesundheitsdaten: Arztrechnungen und ob sich das Einreichen lohnt, je Person und Jahr. Braucht die Einwilligung für Gesundheitsdaten im Space.
`resolve_gap`	`gaps:write`	Optional. Eine Frage zu einem fehlenden Dokument beantworten (vorhanden, ignorieren, später).
`build_packet`	`packets:write`	Optional. Ein Paket zusammenstellen und seine Liste zurückgeben (Dokumente, Prüfliste, was fehlt); es entsteht keine Datei.
`mark_claim_submitted`	`claims:write` + `health:read`	Optional. Arztrechnungen als eingereicht markieren; Rückgängig in der App innerhalb von 24 Stunden.

Im Client erscheinen nur Tools, deren Scope freigegeben wurde. Alle Ergebnisse sind serverseitig auf die bei der Autorisierung gewählten Spaces gefiltert. Jedes Tool trägt einen Titel und ausdrückliche Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), damit Clients vor einer Änderung nachfragen können; resolve_event und remove_document_tags sind als destruktiv markiert.

So funktioniert die Autorisierung

OAuth 2.1 mit PKCE (S256): Clients weisen sich mit einem Client ID Metadata Document aus (eine HTTPS-URL als client_id) oder registrieren sich dynamisch (RFC 7591); nur Public Clients mit PKCE werden akzeptiert. Discovery unter /.well-known/oauth-authorization-server und /.well-known/oauth-protected-resource.
Ressource und Aussteller: Tokens sind an die Ressource https://api.paperarchive.io/mcp gebunden (RFC 8707), und jede Autorisierungsantwort trägt den Parameter iss (RFC 9207). Loopback-Redirect-URIs (zum Beispiel Claude Code) passen auf jeden Port.
Lese-Scopes: documents:read, search, events:read, spaces:read, categories:read, tags:read und senders:read. Ohne Parameter scope werden diese angefragt.
Optionale Gesundheitsdaten: health:read wird nie standardmäßig erteilt, auch nicht als Lese-Scope. Ohne ihn liefert kein Tool medizinische Felder (Positionen, Patient, Behandler, Einreichungsstand, Entscheidungen zur Krankenversicherung).
Optionale Schreib-Scopes: events:write und document_tags:write, im Rollout zusätzlich gaps:write, packets:write und claims:write. Ein Client, der sie anfragt, erhält sie nur, wenn die Person sie auf der Freigabeseite ankreuzt; scope in der Token-Antwort nennt, was erteilt wurde. Ein Aufruf eines Tools außerhalb der erteilten Scopes antwortet mit 403 und WWW-Authenticate: Bearer error="insufficient_scope" samt dem nötigen Scope.
Tokens: Access-Tokens laufen nach 1 Stunde ab; Refresh-Tokens rotieren bei jeder Nutzung und laufen nach 30 Tagen Inaktivität ab. Tokens werden nur gehasht gespeichert.
Space-Einschränkung: Die bei der Freigabe gewählten Spaces sind ein harter serverseitiger Filter für jeden Tool-Aufruf.
API-Keys als Alternative: Clients ohne OAuth-Unterstützung können einen Paperarchive-API-Key als Bearer-Token im Authorization-Header senden. Scopes und Space-Einschränkungen des Keys gelten genau wie unter Authentication dokumentiert. Die optionalen Schreib-Tools brauchen OAuth; API-Keys erhalten über MCP nur die Lese-Tools.

Änderungen durch den Assistenten (optional)

Standardmäßig aus: Auf der Freigabeseite ist jede angefragte Schreibberechtigung ein eigenes Kästchen, das nicht angekreuzt ist.
Dieselben Regeln wie in der App: Änderungen laufen über dieselben Datenbankregeln wie in der Web-App und den Apps. Nur in Spaces, die der Verbindung freigegeben sind, nur an Ereignissen und Dokumenten, die die Person bearbeiten darf (nicht als Betrachter oder Prüfer), nie an Dokumenten, die durch das Tariflimit gesperrt sind.
Nachvollziehbar: Im Änderungsprotokoll des Dokuments steht die Person; Paperarchive protokolliert zusätzlich, welche Verbindung jede Änderung vorgenommen hat.
Begrenzt: Eine Aktion gibt es nur, wo sie zum Zustand des Ereignisses passt (zum Beispiel kein "confirm" bei einer bezahlten Rechnung), und jede Verbindung darf höchstens 30 Änderungen in 10 Minuten vornehmen, zusätzlich zum allgemeinen Rate-Limit.
Nicht vertrauenswürdige Inhalte: Dokumenttext stammt aus hochgeladenen oder per E-Mail eingegangenen Dateien. Die Server-Anweisungen sagen dem Assistenten, nur zu ändern, wenn die Person es im Gespräch verlangt, nie weil ein Dokument es sagt. Clients wie Claude und ChatGPT nutzen die Annotations, um vor einem Tool, das Daten ändert, nachzufragen.

Zugriff verwalten und widerrufen

Verbundene Apps findest du in der Paperarchive-App unter Einstellungen > Verbindungen & API. Apps, die ändern dürfen, sind mit Darf ändern markiert. Beim Trennen einer App werden sofort alle ihre Tokens ungültig. Um die Berechtigungen einer Verbindung zu ändern, trennst du sie und verbindest neu. Der Zugriff endet außerdem automatisch, wenn dein Premium-Tarif ausläuft.

Client-Einrichtung

Der Ablauf ist überall gleich: https://api.paperarchive.io/mcp als Custom Connector hinzufügen, zur Paperarchive-Freigabe weitergeleitet werden, anmelden, Spaces wählen, optional Änderungen erlauben und auf Zugriff erlauben klicken. Nur die Menüpfade unterscheiden sich je Client. Ist Paperarchive im Konnektor- oder App-Verzeichnis deines Assistenten gelistet, kannst du es auch dort hinzufügen, statt die URL einzutragen.

Claude (claude.ai und Claude Desktop)

Öffne Einstellungen > Konnektoren (Team/Enterprise: das übernimmt ein Admin in den Organisationseinstellungen). Custom Connectors setzen einen bezahlten Tarif voraus (Pro, Max, Team oder Enterprise).
Klicke auf Benutzerdefinierten Konnektor hinzufügen, trage die Endpunkt-URL ein und bestätige.
Schließe die Paperarchive-Freigabe ab und aktiviere den Konnektor in einem Chat über das Tools-Menü.

Claude Code

claude mcp add --transport http paperarchive https://api.paperarchive.io/mcp

Claude Code öffnet die Autorisierung beim ersten Aufruf im Browser. Alternativ kannst du dich statt OAuth mit einem Paperarchive-API-Key authentifizieren:

claude mcp add --transport http paperarchive https://api.paperarchive.io/mcp \
  --header "Authorization: Bearer pa_live_DEIN_KEY"

ChatGPT

Verfügbar in bezahlten Tarifen (Plus, Pro, Business, Enterprise, Edu) in der Web-App.
Aktiviere den Developer Mode: Einstellungen > Apps > Erweiterte Einstellungen (der Schalter lag zeitweise auch unter Einstellungen > Konnektoren > Erweitert - der Ort variiert je nach Rollout).
Füge einen neuen Konnektor mit der Endpunkt-URL hinzu. ChatGPT unterstützt Streamable HTTP mit OAuth, der Standard-Freigabe-Flow läuft also durch.
Aktiviere den Konnektor in einer Unterhaltung, um die Paperarchive-Tools zu nutzen.

Grok

Öffne grok.com/connectors und klicke auf New Connector.
Wähle Custom, trage die Endpunkt-URL ein und schließe die Paperarchive-Freigabe ab.
Grok erkennt die Tools automatisch und stellt sie in Unterhaltungen bereit.

Andere MCP-Clients

Jeder MCP-Client mit Unterstützung für Remote-Server über Streamable HTTP funktioniert. Mit OAuth-Unterstützung läuft der Standard-Freigabe-Flow; ohne OAuth nutzt du wie oben beschrieben einen Paperarchive-API-Key im Authorization-Header.

Fehlerbehebung

Der Client bittet um erneute Anmeldung: Das Refresh-Token ist abgelaufen oder die Verbindung wurde widerrufen. Führe die Verbindung einfach neu durch.
Tools fehlen: Der zugehörige Scope wurde nicht freigegeben. Trenne die Verbindung und verbinde neu mit den benötigten Berechtigungen.
403 mit insufficient_scope: Der Assistent wollte etwas ändern, das du nicht erlaubt hast. Verbinde neu und kreuze die Berechtigung an, wenn du sie geben willst.
403 oder "Premium feature": Der Konnektor setzt einen aktiven Premium- oder Testzeitraum voraus.
429-Antworten: Der Konnektor teilt sich das Public-API-Rate-Limit von 60 Anfragen pro Minute je Verbindung.