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.
Endpoint
https://api.paperarchive.io/mcpThe 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. The connection is strictly read-only - MCP clients cannot create, change, or delete anything in your archive.
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. |
Only tools covered by the granted scopes appear in the client. All results are filtered to the Spaces selected during authorization.
How authorization works
- OAuth 2.1 with PKCE (S256): clients register dynamically (RFC 7591); only public clients with PKCE are accepted. Discovery lives at
/.well-known/oauth-authorization-serverand/.well-known/oauth-protected-resource. - Read-only scopes: the connector can request
documents:read,search,events:read,spaces:read,categories:read,tags:read, andsenders:read. Write scopes are not available over MCP. - 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
Authorizationheader. The key's scopes and Space restrictions apply exactly as documented under Authentication.
Managing and revoking access
Connected apps are listed in the Paperarchive app under Settings > API Keys > Connected Apps. Disconnecting an app immediately invalidates all of its tokens. 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, and click Allow access. Only the menu paths differ per client.
Claude (claude.ai and Claude Desktop)
- Open Settings > Connectors (Team/Enterprise: an admin does this under organization settings). Custom connectors require a paid plan (Pro, Max, Team, or Enterprise).
- Click Add custom connector, enter the endpoint URL, and confirm.
- 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/mcpClaude 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
- Available on paid plans (Plus, Pro, Business, Enterprise, Edu) in the web app.
- Enable Developer mode: Settings > Apps > Advanced settings (the toggle has also lived under Settings > Connectors > Advanced - the location varies by rollout).
- Add a new connector with the endpoint URL. ChatGPT supports Streamable HTTP with OAuth, so the standard approval flow runs.
- Enable the connector in a conversation to use the Paperarchive tools.
Grok
- Open grok.com/connectors and click New Connector.
- Select Custom, enter the endpoint URL, and complete the Paperarchive approval flow.
- 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 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.