scangpt.dev · Developer documentation

Receipts, in
your workflow.

The ScanGPT MCP server gives authorized AI assistants access to receipt search, line items and spending summaries. Build the path from an expense question to its original document.

Connect an MCP client

Add a remote MCP server in a compatible client using the current connection URL below. Complete the sign-in flow with your ScanGPT account when the client requests authorization.

The server uses HTTP JSON-RPC and OAuth with PKCE. Client support and connection settings vary. Discover available tools with tools/list after initialization.

First request

After initialization and authorization, a tool call looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_receipts",
    "arguments": {
      "storeName": "Studio Supply",
      "startDate": "2026-09-01",
      "endDate": "2026-09-30",
      "minAmount": 48.90,
      "maxAmount": 48.90
    }
  }
}

This example uses fictional receipt data. Actual results are limited to receipts your account can access.

Core tools

These tool names are present in the existing server. New response fields and additional tools below belong to the prepared ScanGPT release. Use the deployed server’s tools/list schema as the source of truth for your connection.

From a request to the original ScanGPT release

resolve_receipt_requests

Provide up to 25 receipt requests. Each needs a label and can include query, storeName, startDate, endDate, minAmount, maxAmount, entityId, amount, amountTolerance or currency. Amount requests default to EUR and a tolerance of 0.02 in the requested currency. Known other currencies are excluded; candidates without a recorded currency remain ambiguous when matching an amount.

{
  "requests": [
    {
      "label": "Office supplies, September",
      "storeName": "Studio Supply",
      "startDate": "2026-09-01",
      "endDate": "2026-09-30",
      "amount": 48.90
    }
  ]
}

Each result has a status: found, ambiguous or missing, with matching candidates and original-file availability. Preserve ambiguity: show the candidates instead of silently selecting one. Missing means the request was not resolved; it is not a newly created receipt.

Original documents

A receipt’s original value describes whether its stored source file is available:

// Available original
{
  "available": true,
  "url": "https://…",
  "expiresAt": "ISO 8601 timestamp",
  "contentType": "image/jpeg",
  "fileName": "…"
}

// Missing original
{
  "available": false,
  "reason": "…"
}

Original-file links expire after 15 minutes. Fetch or download the file before the link expires, or request a fresh link. Do not turn a missing original into a reconstructed receipt. Use needsReview and reviewReasons to highlight extraction uncertainty; an unverified receipt date may be null.

Prepare an export manifest ScanGPT release

export_receipts

Required input: receiptIds, an array of up to 100 receipt IDs. The response is { format: "manifest", entries, indexCsv }. Entries identify available original files and explicitly report missing ones.

{
  "receiptIds": ["receipt-id-from-search"]
}

The result is a manifest and CSV index. The tool does not produce a ZIP or send email. A client can download available originals, save the index and prepare an attachment bundle for the user to review and send.

HTTP endpoints

Access, review and limits

• The user must authorize the client. Receipt access follows the account’s personal and shared-space access.
• These tools read receipt data. Exporting creates a response manifest; it does not modify the underlying receipts.
• Keep continuation cursors opaque. Continue paging when the response indicates more results.
• Use original documents to check AI-extracted values before completing accounting work.
• Do not send receipts to an accountant or other recipient without the user’s instruction. The MCP tools described here do not deliver messages.
• Retailer connections and receipt extraction can fail or need review. Keep missing files, missing matches and uncertain data visible.

Need help? Contact the ScanGPT team.