> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the OCR API and MCP server

> Call the optical character recognition (OCR) API over REST. Connect a Model Context Protocol (MCP) client without building an intelligent document processing (IDP) agent.

Use this page when you need document text without an intelligent document processing (IDP) agent. Examples include indexing documents in a knowledge base and connecting the Document Retrieval Model Context Protocol (MCP) server to an MCP client such as Cursor. To build an agent that classifies documents and extracts values, see [Build an intelligent document processing agent](https://agenticbanking.backbase.io/agentic-ai/foundation-services/intelligent-document-processing/build-an-idp-agent.md).

## Prerequisites

* **Subscription key**: A key for the API you plan to use. The optical character recognition (OCR) API and the Document Retrieval MCP API have separate subscriptions. To get a key, contact your Backbase support team.
* **Document URL**: A URL that the service can download. Use a public HTTPS URL, an Azure Blob Storage shared access signature (SAS) URL, or a blob in a container that your installation allows. To confirm which containers your installation allows, contact your Backbase support team. For details, see [Document sources](https://agenticbanking.backbase.io/agentic-ai/foundation-services/intelligent-document-processing/reference.md#document-sources).

Set your gateway URL and keys as environment variables so that you can copy the examples on this page:

```bash theme={"system"}
export GATEWAY_URL="https://api.<runtime>.<installation>.gcservices.io"
export OCR_API_KEY="<your_ocr_api_subscription_key>"
export DOCUMENT_RETRIEVAL_API_KEY="<your_document_retrieval_mcp_api_subscription_key>"
```

## Call the OCR API

Use the following operations to get document text.

### Convert a PDF or image

To convert a PDF or image to markdown, send the file URL to the `/convert` endpoint:

```bash theme={"system"}
curl -X POST "$GATEWAY_URL/ocr/v0/convert" \
  -H "api-key: $OCR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://raw.githubusercontent.com/tesseract-ocr/tessdoc/main/images/eurotext.png",
    "mode": "default"
  }'
```

The response contains the markdown and metadata about the run:

```json theme={"system"}
{
  "content": "========== Page 1 ==========\n\nThe (quick) [brown] {fox} jumps!\nOver the $43,456.78 <lazy> #90 dog\n...",
  "metadata": {
    "mode": "default",
    "model": "mistral-ocr-4-0",
    "chunk_count": 1,
    "page_count": 1,
    "output_chars": 442
  }
}
```

If the default mode fails, the service retries with the premium mode, and `metadata.mode` shows the mode that produced the result.

### Fetch a text file

To fetch a TXT, JSON, CSV, MD, or XML file, send the file URL to the `/text` endpoint:

```bash theme={"system"}
curl -X POST "$GATEWAY_URL/ocr/v0/text" \
  -H "api-key: $OCR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://raw.githubusercontent.com/github/gitignore/main/README.md"}'
```

The response contains the file content. Text files don't go through OCR, so `metadata` is `null`:

```json theme={"system"}
{
  "content": "# A collection of `.gitignore` templates\n\n...",
  "metadata": null
}
```

## Connect an MCP client

The Document Retrieval MCP server uses the Streamable HTTP transport at `$GATEWAY_URL/document-retrieval-mcp/v0/mcp`. Send your Document Retrieval MCP API key in the `api-key` header.

**FastMCP client**

```python theme={"system"}
import asyncio
import json
import os

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    url=f"{os.environ['GATEWAY_URL']}/document-retrieval-mcp/v0/mcp",
    headers={"api-key": os.environ["DOCUMENT_RETRIEVAL_API_KEY"]},
)


async def main():
    async with Client(transport) as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools])

        result = await client.call_tool(
            "convert_file_to_markdown",
            {
                "file_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
                "mode": "default",
            },
        )
        body = json.loads(result.content[0].text)
        print(body["metadata"])
        print(body["content"])


asyncio.run(main())
```

**Cursor**

Add the server to `.cursor/mcp.json` in your project root, and then restart Cursor:

```json theme={"system"}
{
  "mcpServers": {
    "document-retrieval": {
      "type": "streamableHttp",
      "url": "https://api.<runtime>.<installation>.gcservices.io/document-retrieval-mcp/v0/mcp",
      "headers": {
        "api-key": "<your_document_retrieval_mcp_api_subscription_key>"
      }
    }
  }
}
```

For other clients, such as Claude Desktop and Agno agents, see [MCP starters](https://agenticbanking.backbase.io/agentic-ai/starter-kits/mcp-starters.md).

## Troubleshooting

> **401: Access denied due to missing or invalid subscription key**
>
> **Cause:** The request has no `api-key` header, or the key belongs to a different API.
>
> **Solution:** Send the key for the API you're calling. The OCR API and the Document Retrieval MCP API use separate subscriptions.

> **404: Resource not found**
>
> **Cause:** The path is missing the version segment.
>
> **Solution:** Include `/v0` in the path, for example `/ocr/v0/convert` or `/document-retrieval-mcp/v0/mcp`.

> **400: Unsupported file type, or container not allowed on POST /text**
>
> **Cause:** The file extension isn't supported by the endpoint. `POST /text` also returns 400 when the blob container isn't allowed and the URL has no SAS token.
>
> **Solution:** Check [Supported file formats](https://agenticbanking.backbase.io/agentic-ai/foundation-services/intelligent-document-processing/reference.md#supported-file-formats). Use `/convert` for PDFs and images and `/text` for text files. For blobs in other containers, pass a SAS URL. On `POST /convert`, a failed download of that blob returns 500.

> **413: File exceeds the size limit**
>
> **Cause:** The file is larger than 50 MB.
>
> **Solution:** Split or compress the document before you send it.

> **429: Rate limit exceeded**
>
> **Cause:** Your subscription exceeded its rate limit.
>
> **Solution:** Wait for the period in the `Retry-After` header and retry. If you need higher throughput, contact your Backbase support team.

> **500: Internal server error**
>
> **Cause:** The service couldn't download the file, or both OCR modes failed. Common reasons are a URL that isn't publicly reachable, an expired SAS token, or a file that doesn't exist. On `POST /convert`, a blob outside the allowlist returns 500 when the HTTPS download fails.
>
> **Solution:** Check that you can download the file from the URL yourself. If the URL works and the error persists, contact your Backbase support team.