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.
Endpunkt
https://api.paperarchive.io/mcpDer 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. Die Verbindung ist strikt schreibgeschützt - MCP-Clients können nichts in deinem Archiv erstellen, ändern oder löschen.
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. |
Im Client erscheinen nur Tools, deren Scope freigegeben wurde. Alle Ergebnisse sind serverseitig auf die bei der Autorisierung gewählten Spaces gefiltert.
So funktioniert die Autorisierung
- OAuth 2.1 mit PKCE (S256): Clients registrieren sich dynamisch (RFC 7591); nur Public Clients mit PKCE werden akzeptiert. Discovery unter
/.well-known/oauth-authorization-serverund/.well-known/oauth-protected-resource. - Nur Lese-Scopes: Der Konnektor kann
documents:read,search,events:read,spaces:read,categories:read,tags:readundsenders:readanfragen. Schreib-Scopes gibt es über MCP nicht. - 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.
Zugriff verwalten und widerrufen
Verbundene Apps findest du in der Paperarchive-App unter Einstellungen > API-Keys > Verbundene Apps. Beim Trennen einer App werden sofort alle ihre Tokens ungültig. 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 und auf Zugriff erlauben klicken. Nur die Menüpfade unterscheiden sich je Client.
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/mcpClaude 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 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.