Prerequisites
- Subscription key for the Document Retrieval MCP API. To get a key, contact your Backbase support team.
- AI gateway access for the language model that powers your agent. See AI gateway.
- Document URLs that the optical character recognition (OCR) service can download. See Send documents to the agent.
Connect the agent to the MCP server
Add the Document Retrieval MCP server to your agent as a tool source, at{baseURL}/document-retrieval-mcp/v0/mcp with your subscription key in the api-key header. The server exposes two tools: convert_file_to_markdown for PDFs and images, and fetch_text_content for text files. For client setup, see Connect an MCP client.
Set the tool call timeout high enough for long documents, because OCR on a large PDF can take minutes.
Add the template instructions
The following template covers one use case: classify a banking document and extract a single requested value from it. For example, the agent returns the registration number from a Dutch Chamber of Commerce extract (Kamer van Koophandel, KvK). The agent can also return the net pay from a payslip, or total assets from a balance sheet. The template returns the value exactly as printed, as a JSON object with the document type and the value.other as the last type.
Other use cases need different instructions. For example, extracting several fields at once, summarizing a document, comparing two documents, or answering open questions about a document each need their own tasks and output format. You can reuse the Tools section of this template in any instructions that use the Document Retrieval MCP server.
error_message to the output. Tell the agent when to fill that key. For example: “If the document isn’t the type the user asked about, set extracted_value to NOT_FOUND and explain why in error_message.”
Send documents to the agent
The agent reads documents from URLs, so your app stores the uploaded file first and then passes a URL to the agent. Use one of these options:- Signed URLs from Document Storage: Store the file with Backbase Document Storage and pass a time-limited signed URL. See Use signed URLs.
- Azure Blob Storage shared access signature (SAS) URLs: Pass a URL with a SAS token.
- Allowed Blob Storage containers: Pass a plain blob URL for containers that your installation allows. The OCR service reads these with its managed identity.
Handle the result
The agent returns a JSON object like the following:- If
document_typeisn’t the type you expected, ask the customer for the right document. - If
extracted_valueisNOT_FOUND, route the document to a person for review. - If the response isn’t valid JSON, retry once, and then route the document for review.
Related topics
- Overview for how IDP works and when to use it.
- Use the OCR API and MCP server to call the services without an agent.
- Reference for supported formats, document sources, limits, and error codes.