MCP Connector

Paperarchive ships a remote Model Context Protocol (MCP) server. Once connected, an AI assistant such as Claude, ChatGPT, or Grok can search your archive, read document details, look up bank statement transactions, and hand you download links - directly from a conversation. If you allow it, the assistant can also mark invoices as paid, resolve other events, and add or remove tags.

Endpoint

https://api.paperarchive.io/mcp

The server speaks MCP over Streamable HTTP and authenticates via OAuth 2.1. Any MCP client that supports remote servers with OAuth can connect. Authorization happens in the Paperarchive app: you log in, review the requested permissions, choose which Spaces the connection may access, and approve. By default the connection is read-only. Changes (resolving events, tagging documents) are separate permissions that stay off until the user ticks them on the consent page. Uploading, deleting, or reprocessing documents is never possible over MCP.

Requirements

• A Paperarchive account with an active Premium or trial plan (same requirement as API keys).
• An MCP client that supports remote servers, for example Claude, ChatGPT, or Grok (see the setup guides below).

Available tools

Tool	Scope	Description
search_documents	search	Full-text search across titles, senders, categories, tags, and OCR text.
list_documents	documents:read	Browse documents with filters (space, category, status, date) and pagination.
get_document	documents:read	Document details incl. extracted fields, tags, and optionally OCR text.
get_document_download_link	documents:read	Short-lived signed URL (10 minutes) for the original file.
list_statements	documents:read	Bank statements with extracted structured data.
get_statement_transactions	documents:read	Transactions, balances, IBAN, and period of a statement.
list_events	events:read	Events (invoices, contracts, policies, ...) with state, amount, and due date - answers questions like "What is open or due?".
get_event	events:read	Details of a single event incl. amounts, deadlines, reference number, and source document.
list_spaces	spaces:read	Spaces the connection can access.
list_categories	categories:read	Categories for filtering documents.
list_tags	tags:read	Tags in the accessible Spaces.
list_senders	senders:read	Detected senders in the accessible Spaces.
resolve_event	events:write	Optional. Resolve one event: paid, confirm, archive, or cancel (same rules as in the app).
add_document_tags	document_tags:write	Optional. Add existing tags (ids from list_tags) to a document.
remove_document_tags	document_tags:write	Optional. Remove tags from a document; Paperarchive will not add them back automatically.

In the rollout (not yet available for every account), accounts with the to-do features also get these tools:

Tool	Scope	Description
get_week_ahead	events:read	The at most three most urgent things to do this week, each with its decision.
list_gaps	documents:read	Open questions about expected documents (a bank transaction without a receipt, a document an application still needs).
get_property_overview	documents:read	Rented-out property: rent, next possible increase, service charge deadline (usual rules, no legal advice).
get_investments	documents:read	Depots from the depot statements: value, gain, return per year, with an id the positions and payments (no market data from the internet, no investment advice).
get_retention_expired	documents:read	Documents of private spaces whose usual retention period ended; nothing is deleted.
get_health_overview	health:read	Optional, health data: medical invoices and whether submitting them pays off, per person and year. Needs the health consent of the space.
resolve_gap	gaps:write	Optional. Answer a question about a missing document (present, ignore, later).
build_packet	packets:write	Optional. Put a packet together and return its list (documents, checklist, what is missing); no file is created.
mark_claim_submitted	claims:write + health:read	Optional. Mark medical invoices as submitted; undo in the app within 24 hours.

Only tools covered by the granted scopes appear in the client. All results are filtered to the Spaces selected during authorization. Every tool carries a title and explicit annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can ask for confirmation before a change; resolve_event and remove_document_tags are marked as destructive.

How authorization works

• OAuth 2.1 with PKCE (S256): clients identify themselves with a Client ID Metadata Document (an HTTPS URL as client_id) or register dynamically (RFC 7591); only public clients with PKCE are accepted. Discovery lives at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.
• Resource and issuer: tokens are bound to the resource https://api.paperarchive.io/mcp (RFC 8707), and every authorization response carries the iss parameter (RFC 9207). Loopback redirect URIs (for example Claude Code) match on any port.
• Read scopes: documents:read, search, events:read, spaces:read, categories:read, tags:read, and senders:read. Without a scope parameter, these are requested.
• Optional health data: health:read is never granted by default, not even as a read scope. Without it no tool returns medical fields (positions, patient, provider, claim states, health insurance decisions).
• Optional write scopes: events:write and document_tags:write, in the rollout also gaps:write, packets:write and claims:write. A client that requests them gets them only if the user ticks them on the consent page; the token response's scope names what was granted. A call to a tool outside the granted scopes answers 403 with WWW-Authenticate: Bearer error="insufficient_scope" and the needed scope.
• Tokens: access tokens expire after 1 hour; refresh tokens rotate on every use and expire after 30 days of inactivity. Tokens are stored hashed.
• Space restriction: the Spaces you select at approval time are a hard server-side filter for every tool call.
• API keys as an alternative: clients without OAuth support can send a Paperarchive API key as a Bearer token in the Authorization header. The key's scopes and Space restrictions apply exactly as documented under Authentication. The optional write tools need OAuth; API keys only get the read tools over MCP.

Changes through the assistant (optional)

• Off by default: on the consent page every requested write permission is a separate checkbox that starts unticked.
• Same rules as the app: changes run through the same database rules as the web and mobile apps. Only Spaces granted to the connection, only events and documents the user may edit (not as viewer or auditor), never on documents locked by the plan limit.
• Traceable: the change log of the document names the user; Paperarchive also logs which connection made each change.
• Limited: an action is only available where it fits the event's state (for example no "confirm" on a paid invoice), and each connection can make at most 30 changes per 10 minutes on top of the general rate limit.
• Untrusted content: document text comes from uploaded or emailed files. The server instructions tell the assistant to change things only when the user asks in the conversation, never because a document says so. Clients such as Claude and ChatGPT use the annotations to ask before they run a tool that changes data.

Managing and revoking access

Connected apps are listed in the Paperarchive app under Settings > Connections & API. Apps that may make changes are marked Can make changes. Disconnecting an app immediately invalidates all of its tokens. To change the permissions of a connection, disconnect it and connect again. Access also ends automatically when your Premium plan lapses.

Client setup

The connection flow is the same everywhere: add https://api.paperarchive.io/mcp as a custom connector, get redirected to Paperarchive, log in, pick your Spaces, optionally allow changes, and click Allow access. Only the menu paths differ per client. If Paperarchive is listed in your assistant's connector or app directory, you can add it from there instead of entering the URL.

Claude (claude.ai and Claude Desktop)

1. Open Settings > Connectors (Team/Enterprise: an admin does this under organization settings). Custom connectors require a paid plan (Pro, Max, Team, or Enterprise).
2. Click Add custom connector, enter the endpoint URL, and confirm.
3. Complete the Paperarchive approval flow, then enable the connector in a chat via the tools menu.

Claude Code

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

Claude Code opens the authorization flow in your browser on first use. Alternatively, authenticate with a Paperarchive API key instead of OAuth:

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

ChatGPT

1. Available on paid plans (Plus, Pro, Business, Enterprise, Edu) in the web app.
2. Enable Developer mode: Settings > Apps > Advanced settings (the toggle has also lived under Settings > Connectors > Advanced - the location varies by rollout).
3. Add a new connector with the endpoint URL. ChatGPT supports Streamable HTTP with OAuth, so the standard approval flow runs.
4. Enable the connector in a conversation to use the Paperarchive tools.

Grok

1. Open grok.com/connectors and click New Connector.
2. Select Custom, enter the endpoint URL, and complete the Paperarchive approval flow.
3. Grok discovers the tools automatically and makes them available in conversations.

Other MCP clients

Any MCP client that supports remote Streamable HTTP servers works. With OAuth support, the standard approval flow runs; without it, use a Paperarchive API key in the Authorization header as described above.

Troubleshooting

• The client asks to re-authenticate: the refresh token expired or the connection was revoked. Re-run the connect flow.
• Tools are missing: the corresponding scope was not granted. Disconnect and reconnect with the needed permissions.
• 403 with insufficient_scope: the assistant tried a change you did not allow. Reconnect and tick the permission if you want it.
• 403 or "Premium feature": the connector requires an active Premium or trial plan.
• 429 responses: the connector shares the public API rate limit of 60 requests per minute per connection.