Use the OCR API and MCP server

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.

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.

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

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:

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:

{
  "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:

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:

{
  "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
Cursor

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())

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

{
  "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.

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. 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.

Agent Platform

Architecture and technology

Agent Development Lifecycle

Get started

Starter kits

CI/CD workflows

BB AI SDK

MCP

Foundation services

Prerequisites

Call the OCR API

Convert a PDF or image

Fetch a text file

Connect an MCP client

Troubleshooting

​Prerequisites

​Call the OCR API

​Convert a PDF or image

​Fetch a text file

​Connect an MCP client

​Troubleshooting

Prerequisites

Call the OCR API

Convert a PDF or image

Fetch a text file

Connect an MCP client

Troubleshooting