DEV Community: OCR-AI

Giving Claude and Cursor a Hebrew OCR tool over remote MCP

OCR-AI — Sat, 07 Nov 2026 11:47:50 +0000

By the OCR-AI team

Language models are decent at reading images now, but ask one to pull the allocation number, VAT and line items out of a scanned Hebrew invoice and check them against a spreadsheet, and you'll spend more time correcting it than you saved. A better split is to give the agent a tool that reads the document into structured data, and let the model do the reasoning on top.

This post shows how to connect our remote MCP server to an MCP client like Claude or Cursor, what the tools do, and a few things we learned about running OCR behind MCP.

The server

The endpoint is https://ocr-ai.com/mcp. It uses the Streamable HTTP transport and is stateless: every POST gets one JSON response, with no session and no event stream. Supported protocol versions are 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

initialize and tools/list work without a key, so a client can discover the tools before you've set anything up. Actually calling a tool needs an API key, sent as a Bearer token.

There are three tools:

Tool	Arguments	Returns
`read_document`	`file_url` or `file_base64`; optional `pages` (e.g. `"1-5,8"`), `hint` (`auto`, `invoice`, `receipt`, `card`, `table`, `text`), `language` (`en` or `he`)	Markdown text, plus `structuredContent` with the full document object
`check_balance`	none	balance, whether pages expired, a `buy_url`, the packs
`buy_pages`	`pack` (`p100`, `p500`, `p2000`), `currency` (`USD` or `ILS`)	a `buy_url` for that pack

Getting a key

Keys come from the agents page. You leave an email, get a sign-in link (no password, no card), and create a key on your account page. The key is shown once, so copy it then. An account's first key starts with 100 free pages.

Keep the key on the server side or in your local client config. Don't put it in a web page or a mobile app.

Configuration

Most MCP clients that support remote servers take a URL and headers. This is the config from our docs:

{
  "mcpServers": {
    "ocr-ai": {
      "type": "http",
      "url": "https://ocr-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer ocrai_sk_…"
      }
    }
  }
}

Replace ocrai_sk_… with your key. In Cursor that block goes in your MCP config file (mcp.json). Clients differ a little in where the file lives and whether they want "type": "http" or another name for the transport, so check your client's own docs if it doesn't pick the server up. The fields that matter are the URL and the Authorization header.

If you want to check the server before wiring up a client, you can call a tool with plain curl:

curl https://ocr-ai.com/mcp \
  -H "Authorization: Bearer ocrai_sk_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "read_document",
                  "arguments": {"file_url": "https://example.com/invoice.pdf"}}}'

What a session looks like

Once connected, you can just ask. Something like "read this invoice and tell me the vendor, invoice number and total" with a link to a PDF. The agent calls read_document with file_url and hint: "invoice", and gets back fields like vendor_name, document_number, issue_date and total, each with a normalized value (dates as YYYY-MM-DD, amounts as plain decimals), plus the line-item table and the full text in reading order.

Because the field keys are fixed, the model doesn't have to guess what "סה״כ לתשלום" means. It's total. That makes follow-up work much more reliable: comparing three supplier quotes, checking that a delivery note matches a purchase order, or filling a CSV with one row per invoice.

Fields that were hard to read come back with "uncertain": true. It's worth telling the agent, in your prompt or rules file, to point those out rather than silently using them.

file_url has to be a public https link with no credentials in it, and the download must finish within 20 seconds. For a local file, the client can send file_base64 instead.

Errors are written for the model

This is the design choice we'd recommend to anyone building an MCP server. Problems a model can act on don't come back as protocol errors. They come back as tool results with isError: true, a plain sentence, and a code in structuredContent.error.

The main example is running out of pages. A call is checked before anything is read, and if the account has fewer pages than the call needs, nothing is read and nothing is charged. The tool result says how many pages were needed, how many are left, and includes a buy_url. The agent can hand that link to you, you pay on Stripe's page, and the agent calls again. The link only adds pages to the key's account; it doesn't sign anyone in, so it's safe to pass along.

Other codes the model can handle the same way: missing_key and invalid_key (with a link to get a key), rate_limited, bad_pages, fetch_failed, unsupported_type.

Timeouts

One practical gotcha. A read_document call can cover up to 20 pages, and many pages can take more than a minute. MCP clients stop waiting after a set time; the MCP TypeScript SDK defaults to 60 seconds. If you see timeouts on long PDFs, raise the timeout for that tool if your client allows it, or ask the agent to read in smaller ranges with pages.

Billing on timeouts is spelled out in the docs: if the connection closes before the answer is sent, the call is refunded in full. If the client stops waiting but keeps the connection open, those pages are charged. Failed pages are always given back.

Why remote and not local

A local MCP server that wraps Tesseract is easy to build, and for clean English text it's fine. For Hebrew invoices you'd still own the bidi handling, the layout logic and the field extraction. A remote server means one URL and one header in the config, and the same tool works from any client.

The trade-off is that the document leaves your machine. Our docs and security page say files are read in memory and not stored on the server, but you should make that call for your own documents.

Links

Docs, including every error code: ocr-ai.com/en/docs. There's a Markdown copy at /docs.md you can drop into an agent's context. And if you want to see the output on your own invoice before setting anything up, the browser version reads 5 pages a day free with no signup.

Pulling fields out of Hebrew invoices with a REST API

OCR-AI — Sat, 07 Nov 2026 11:46:11 +0000

By the OCR-AI team

If you've ever run a scanned Israeli tax invoice through a general-purpose OCR library, you know the output. The words come back in the wrong order, the phone number is split across two lines, and the total ends up somewhere next to the vendor's address. You can fix some of it with post-processing. Most people give up and retype.

This post walks through reading Hebrew invoices and receipts with our REST API, and then spends some time on why this is harder than it looks, because that part applies no matter which tool you use.

The one endpoint you need

Reading a document is a single call: POST https://ocr-ai.com/api/v1/read. It accepts PDF, JPEG, PNG and WebP, and you authenticate with an API key as a Bearer token (Authorization: Bearer ocrai_sk_...; an X-API-Key header also works).

You can send the file three ways:

multipart/form-data, with the file in a field called file
JSON, with file_base64 or file_url (a public https link)
the raw bytes, with the file's own Content-Type, and the options as query parameters

The options are the same in each case: pages (like "1-3" or "1-5,8"), hint (auto, invoice, receipt, card, table or text) and language for labels and the summary (en or he).

Upload from disk:

curl https://ocr-ai.com/api/v1/read \
  -H "Authorization: Bearer $OCRAI_KEY" \
  -F "file=@invoice.pdf" \
  -F "pages=1-3"

Or point it at a URL:

curl https://ocr-ai.com/api/v1/read \
  -H "Authorization: Bearer $OCRAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/invoice.pdf", "hint": "invoice"}'

One thing worth knowing: the server decides the file type from the bytes, not from the name or the declared type. And unknown fields are rejected with a 400 bad_request that names the offending field, which is nice when you typo hnit.

What comes back

The response is a document object. At the top level you get page accounting (total_pages, pages_read, pages_charged, balance, next_pages), and then pages[], one entry per page. Each page that was read has a document_type, a language, a short summary, plus fields, tables and the full text in reading order.

Fields are the interesting part. Each one has a key, a human label, the value as printed, a type, and where it applies a normalized value and a box:

{
  "key": "issue_date",
  "label": "תאריך הפקה",
  "value": "21/10/2026",
  "normalized": "2026-10-21",
  "type": "date",
  "box": [144, 706, 163, 798]
}

normalized is what you actually want to store: dates as YYYY-MM-DD, money as a plain decimal ("6,018.00 ₪" becomes "6018"). The box is [ymin, xmin, ymax, xmax] on a 0-1000 scale relative to the page, so you can draw a highlight over the scan in a review UI. If a value was hard to read, the field carries "uncertain": true.

The keys are fixed. For invoices you'll see things like vendor_name, vendor_tax_id, document_number, allocation_number, issue_date, due_date, subtotal, vat_rate, vat_amount, total and currency. Line items arrive as a table with columns and rows.

A small Python script

Here's a minimal script that reads an invoice and prints the header fields plus the line items. It uses only the documented endpoint and response shape.

import os
import requests

KEY = os.environ["OCRAI_KEY"]

def read_invoice(path):
    with open(path, "rb") as f:
        r = requests.post(
            "https://ocr-ai.com/api/v1/read",
            headers={"Authorization": f"Bearer {KEY}"},
            files={"file": f},
            data={"hint": "invoice", "language": "en"},
            timeout=180,  # multi-page calls can take over a minute
        )
    if r.status_code == 402:
        body = r.json()
        raise SystemExit(f"Out of pages: {body['message']} -> {body['buy_url']}")
    r.raise_for_status()
    return r.json()

doc = read_invoice("invoice.pdf")

for page in doc["pages"]:
    if page["status"] != "done":
        print(f"page {page['page']}: {page['status']} {page.get('error', '')}")
        continue
    fields = {f["key"]: f for f in page["fields"]}
    for key in ("vendor_name", "vendor_tax_id", "document_number",
                "allocation_number", "issue_date", "vat_amount", "total"):
        f = fields.get(key)
        if f:
            flag = "  <- check" if f.get("uncertain") else ""
            print(f"{key:18} {f.get('normalized', f['value'])}{flag}")
    for table in page["tables"]:
        print(table["columns"])
        for row in table["rows"]:
            print(row)

A few details in there are deliberate. The long timeout is because a call can read up to 20 pages and that can take more than a minute. The per-page status check matters because a call can succeed while one page fails; a failed page is given back (refunded: true) and has an error such as engine_busy, which you can simply retry. And the 402 branch exists because when the account has fewer pages than the call needs, nothing is read or charged. You get a buy_url instead.

Limits to plan around: 20 pages per call, 20 MB per file, 28 MB per request body, roughly 30 calls a minute per key. If a PDF has more pages than one call reads, next_pages tells you the range to ask for next.

Why Hebrew OCR is genuinely hard

None of this is specific to us. If you're evaluating any tool, these are the places to test.

Bidirectional text. Hebrew runs right to left, but numbers, dates, email addresses and English product names inside it run left to right. A PDF stores characters in some order, and a viewer applies the Unicode bidi algorithm to display them. Copy text out of a lot of Hebrew PDFs and you get the stored order, which is why "reversed Hebrew" is such a common complaint. Reversing the string fixes the Hebrew and breaks every number.

Mixed numbers and currency. An invoice line like 2 × 680.00 = 1,360.00 ₪ has to survive with the digits in order and the shekel sign attached to the right number. Thousands separators and decimal points look like noise to a naive tokenizer. Getting this wrong is worse than getting a word wrong, because nobody notices until the books don't balance.

Layout. Israeli invoices tend to put the vendor block top right, the customer block top left, and a table whose first column is on the right. Reading order for a page like that isn't "top to bottom, left to right" or even its mirror image.

Nikud and look-alike letters. Most business documents don't use vowel points, but some printed material does, and stray dots from a bad scan can be mistaken for them. Several letters differ by a tiny stroke (ד and ר, ה and ח, ו and ן), which is exactly the detail a faded thermal receipt loses.

Fonts. Hebrew typography is a smaller world, and a lot of invoices are produced by older accounting software with idiosyncratic fonts, or printed on thermal paper that fades within months.

So treat the output as something to check, not something to trust blindly. That's why every field has a box and an uncertainty flag: in a pipeline, route anything marked uncertain to a person, and let the rest through.

Trying it without code

If you just want to see what a given invoice produces, the browser version at ocr-ai.com reads 5 pages a day free, with no signup. For the API, an account's first key starts with 100 free pages. The full reference, including every error code, is at /docs, and there's a Markdown copy at /docs.md if you want to paste it into a model's context.