How to integrate the ACJ Labs receipt extraction MCP server

This guide covers the mechanical integration steps for the ACJ Labs receipt extraction MCP server: client configuration, authentication, schema definitions, and error handling, so you can consume the extract_receipt tool via standard JSON-RPC transport (or plain HTTPS) without reading the source.

Q: How do I install / add this MCP server?

Add the remote HTTP endpoint to your client configuration. For Claude Code:

claude mcp add --transport http receipt-extraction \
  https://receipt-extraction.acjlabs.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Other developer clients — Cursor, Cline, VS Code — connect identically: point at the same URL and supply the same Bearer header in their remote-server settings.

https://acjlabs-receipt-extraction.acjlabs.workers.dev/mcp is an alternate address for the same deployment. If that is what you already have configured, it keeps working — there is nothing to migrate.

Q: How do I authenticate — where does the API key go?

Request a free-tier key via POST /v1/signup with { "email": "you@example.com" }. The response body contains your key, shown once and unrecoverable if lost — store it immediately. Pass it in the Authorization: Bearer YOUR_API_KEY header on every tool call. Schema discovery (initialize/ tools/list) works unauthenticated; only calling extract_receipt triggers entitlement checks.

Q: What’s the input — what do I pass to the tool?

Call extract_receipt with a JSON object containing document_base64 (your image or PDF, base64-encoded) and mime_type (e.g. image/jpeg). The server decodes the payload, runs it through the vision-extraction adapter, and normalizes the result before returning structured data.

Q: What’s the output schema?

A versioned Receipt object: vendor (name, abn, boolean abn_valid), date, totals, and an array of line_items. Each line item carries description, qty, unit_price, gst, tax_code, a confidence score (0–1), and a rationale string naming the exact rule applied. tax_code is assigned via mechanical classification against documented AU GST rules — the system extracts and flags values, it does not provide professional tax advice.

Q: How does it handle the cases it can’t resolve?

Every normalized result is validated with isValidReceipt; if validation fails, or the vision provider call errors, the tool returns a graceful MCP isError: true response rather than crashing. For unreadable documents, required string fields default to an empty string "" instead of null. Invalid ABN checksums are transcribed verbatim — never silently “corrected” — with downstream validation flagging them.

Q: Are there rate limits / quotas?

Quotas are enforced server-side per API key. Free tier: 20 documents/month, 10 requests/minute. Pro tier: 120 requests/minute. Exceeding the monthly quota returns 402; exceeding the per-minute rate limit returns 429; a missing or invalid key returns 401.

Q: Is there a client library?

Yes — @acjlabs/receipt-extraction-client on npm, so you don’t hand-roll JSON-RPC calls:

npm install @acjlabs/receipt-extraction-client

const receipt = await client.extractReceipt(base64EncodedImageOrPdf, "image/png");

A minimal end-to-end example

{
  "tool": "extract_receipt",
  "input": {
    "document_base64": "<base64 image or PDF>",
    "mime_type": "image/jpeg"
  }
}

{
  "vendor": { "name": "Acme Pty Ltd", "abn": "51824753556", "abn_valid": true },
  "date": "2026-07-14",
  "line_items": [
    {
      "description": "Widget",
      "qty": 2,
      "unit_price": 12.5,
      "gst": 2.5,
      "tax_code": "taxable",
      "confidence": 0.95,
      "rationale": "Standard-rated retail good; 10% GST applies."
    }
  ],
  "totals": { "subtotal": 25.0, "gst": 2.5, "total": 27.5 },
  "schema_version": "1.0"
}

Q: How does pricing and entitlement work?

The @acjlabs/entitlement middleware checks entitlement on every extract_receipt call before extraction runs — each key carries a plan (free/pro) with a monthly document quota and a per-minute request rate limit. Free keys self-serve via POST /v1/signup. Paid tiers aren’t self-serve yet (billing isn’t live pre-revenue) — the free tier is the only self-serve plan today.

See the FAQ for pricing and accuracy details, or Products for the quick-start.

GST handling reflects publicly documented Australian tax law and is provided as software output, not tax advice.