Connect Ocrolus to ChatGPT: Analyze Documents & Detect Fraud

If your team uses Claude, check out our guide on connecting Ocrolus to Claude or explore our broader architectural overview on connecting Ocrolus to AI Agents.

Financial institutions rely on Ocrolus to classify documents, verify income, and detect tampered bank statements. Integrating Large Language Models (LLMs) with this data pipeline allows teams to build autonomous agents that can triage loan applications, extract self-employed income calculations, and red-flag fraudulent documents using natural language. But giving an LLM read and write access to Ocrolus requires a highly secure, reliable integration layer.

You need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and the REST endpoints of the Ocrolus API. You can either spend weeks building, hosting, and maintaining a custom MCP server, or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to bypass the boilerplate, generate a secure MCP server for Ocrolus, connect it natively to ChatGPT, and execute complex fraud detection workflows.

The Engineering Reality of the Ocrolus API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized fintech APIs - or maintaining custom connectors for 100+ other platforms - is an engineering headache.

If you decide to build a custom MCP server for Ocrolus, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Ocrolus:

The Async Processing Threshold Ocrolus handles massive volumes of transaction data, and its API behaves differently depending on the scale of the payload. For endpoints like ocrolus_cash_flow_get_features or ocrolus_books_get_summary, synchronous requests work fine for small files. However, if a Book contains more than 100,000 transactions, you must explicitly set async=true in the payload, which forces your MCP server to handle a completely different asynchronous job-polling lifecycle. Books exceeding 1,000,000 transactions are rejected outright. If your custom MCP server doesn't parse these limits and instruct the LLM on how to poll for job completion, your AI agent will crash waiting for a response.

Mutually Exclusive Identifiers The Ocrolus API enforces strict parameter exclusivity. Many endpoints require either a book_uuid or a primary key (pk), but will throw a hard error if you provide both - or neither. Exposing this logic to an LLM requires perfectly crafted JSON schemas. If the LLM's tool definitions do not use oneOf or explicitly document this mutual exclusivity, the model will frequently hallucinate a payload with both identifiers, causing the tool call to fail.

Strict API Rate Limits and 429 Errors Ocrolus enforces rate limits on concurrent uploads and heavy analytics endpoints. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API like Ocrolus returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - your application or the LLM framework - is entirely responsible for implementing the retry and exponential backoff logic.

Underwriting Guideline Specificity When calculating income, Ocrolus endpoints behave differently based on the underwriting guideline specified (e.g., FANNIE_MAE, FREDDIE_MAC, FHA, VA, USDA). If your LLM attempts to fetch a summary without knowing the organization's default guideline, the calculated data will be misaligned with your compliance requirements.

The Managed MCP Approach

Instead of forcing your engineering team to build authentication middlewares, flat-namespace query parsers, and custom tool registries for Ocrolus, Truto handles the infrastructure. Truto's MCP server turns any connected Ocrolus account into an LLM-ready tool server dynamically, based on curated integration documentation and existing API schemas.

Here is how to set it up.

Step 1: Generating the Ocrolus MCP Server

Every MCP server in Truto is scoped to a single integrated account. This means the server URL contains a cryptographically secure token that authenticates the LLM directly to that specific tenant's Ocrolus data. You can generate this server via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

1. Navigate to the Integrated Account page for your connected Ocrolus instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server (assign a name, optionally filter to read methods only, and set an expiration date).
5. Copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method B: Via the API For platforms provisioning AI agents programmatically, you can generate the MCP server via a REST call. This provisions the token, stores it securely, and returns a ready-to-use URL.

curl -X POST https://api.truto.one/integrated-account/{account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ocrolus Fraud Analyst Agent",
    "config": {
      "methods": ["read", "custom"],
      "tags": ["fraud", "analytics"]
    }
  }'

The API validates the configuration, ensures tools exist for the requested filters, and returns the endpoint URL:

{
  "id": "mcp-7a8b9c",
  "name": "Ocrolus Fraud Analyst Agent",
  "config": { "methods": ["read", "custom"], "tags": ["fraud", "analytics"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Step 2: Connecting the MCP Server to ChatGPT

Once you have the URL, you need to register it with your LLM client so it can run the MCP initialize handshake and request the tools/list.

Method A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle (MCP support is gated behind this flag).
3. Under MCP servers / Custom connectors, click to add a new server.
4. Name: Ocrolus Agent
5. Server URL: Paste the Truto MCP URL you generated.
6. Save the configuration. ChatGPT will immediately connect and fetch the available tools.

Method B: Via Manual Config File (Standard LLM Frameworks) If you are running a custom agent framework (like LangChain, Cursor, or Claude Desktop), you can connect to the Truto remote MCP server using the official Server-Sent Events (SSE) wrapper. Configure your MCP settings JSON file as follows:

{
  "mcpServers": {
    "ocrolus": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

When the LLM starts, it invokes this command, bridging its internal tool-calling engine to your remote Truto endpoint.

Hero Tools for Ocrolus

Truto dynamically generates specific snake_case tools from the Ocrolus API schemas. Below are the most critical, high-leverage tools available to your AI agent for fraud and document analysis.

ocrolus_documents_upload_pdf

This tool allows the agent to ingest new PDF documents into an existing Ocrolus Book for typed processing. The LLM must supply the upload file reference, the book_uuid, and the expected form_type.

"I have a new bank statement file ready for review. Upload the PDF located at /tmp/statement_oct.pdf to the Ocrolus book 'uuid-1234' as a BANK_STATEMENT form type, and let me know when the upload is complete."

ocrolus_books_get_fraud_signals

This is the core tool for detecting tampered documents. It returns the fraud analysis results, including file metadata anomalies, font mismatch detection, and a direct link to the dashboard visualization.

"Retrieve the fraud signals for the loan application book 'uuid-9876'. Summarize any high-risk anomalies detected in the document structure and provide the dashboard URL for manual review."

ocrolus_cash_flow_get_risk_score

This tool retrieves the cash flow risk score for an entire Book, analyzing all contained bank statements. It is essential for determining a borrower's financial health and stability.

"Calculate the cash flow risk score for book 'uuid-5544'. If the score indicates high volatility or declining average balances, draft a warning note for the underwriting team."

ocrolus_income_calculate_self_employed_fm

Automates the complex process of calculating self-employed income using Fannie Mae guidelines. The LLM must pass the book_uuid, borrower_uuid, and business_uuid.

"Run the Fannie Mae self-employed income calculation for borrower 'borrower-777' on business 'business-888' inside book 'uuid-1122'. Extract the net qualifying income from the response."

ocrolus_transactions_list_enriched

Retrieves a deeply enriched list of transactions for a Book, including enrichment tags, standard categories, and counterparty identification. This is crucial for spending analysis.

"List the enriched transactions for book 'uuid-3333'. Group the transactions by counterparty and identify the top three recurring expenses over the last 90 days."

ocrolus_books_get_classification_summary

Before running deep analytics, you need to know what documents are actually in the Book. This tool returns the classification summary, breaking down form types and highlighting any detected duplicates.

"Pull the document classification summary for book 'uuid-4455'. Verify that at least three consecutive months of bank statements were successfully classified, and flag any duplicate uploads."

To view the complete schema definitions and the dozens of other endpoints available - including tools for webhooks, custom tags, and Encore book copy jobs - visit the Ocrolus integration page.

Workflows in Action

Giving an AI agent access to individual tools is useful, but the real power of MCP is orchestrating multi-step workflows. Here is how ChatGPT can act as an autonomous underwriter or fraud investigator.

sequenceDiagram
    participant User as Underwriter
    participant LLM as ChatGPT
    participant MCPServer as Truto MCP Server
    participant Ocrolus as Ocrolus API

    User->>LLM: "Review applicant Smith's file for fraud and income."
    LLM->>MCPServer: Call ocrolus_books_get_fraud_signals
    MCPServer->>Ocrolus: GET /v1/book/uuid-123/fraud
    Ocrolus-->>MCPServer: Return fraud metadata
    MCPServer-->>LLM: JSON response
    LLM->>MCPServer: Call ocrolus_income_calculate_self_employed_fm
    MCPServer->>Ocrolus: POST /v1/income/calculate
    Ocrolus-->>MCPServer: Return income attributes
    MCPServer-->>LLM: JSON response
    LLM-->>User: "No fraud detected. Qualifying income is $8,400/mo."

Scenario 1: End-to-End Fraud Investigation

When a new merchant cash advance application comes in, the agent is tasked with verifying the integrity of the submitted bank statements before clearing them for funding.

"The applicant provided a new set of bank statements under book 'uuid-8899'. Pull the document classification summary to ensure they are actually bank statements. If they are, run a fraud signal check. If any font anomalies or digital tampering are detected, draft a rejection notice citing the specific pages affected."

How the agent executes this:

1. Calls ocrolus_books_get_classification_summary to verify the document types match the expected BANK_STATEMENT class.
2. Calls ocrolus_books_get_fraud_signals to retrieve the forensic analysis.
3. Parses the JSON response for doc_analysis flags indicating PDF metadata scrubbing or inconsistent text layers.
4. Synthesizes the findings and outputs a structured summary for the risk team.

Scenario 2: Self-Employed Borrower Assessment

Underwriting self-employed applicants requires extracting specific income data across multiple business lines, a traditionally manual process.

"For the mortgage application under book 'uuid-2233', first verify the cash flow risk score. If the score is acceptable, proceed to calculate the self-employed income using Fannie Mae guidelines for borrower 'borrower-01' and business 'biz-02'. Provide the final monthly qualifying income."

How the agent executes this:

1. Calls ocrolus_cash_flow_get_risk_score to assess historical cash flow stability.
2. Evaluates the risk metrics returned in the payload.
3. Calls ocrolus_income_calculate_self_employed_fm with the required UUIDs.
4. Extracts the calculated attributes payload and formats the final monetary figure for the loan officer.

Security and Access Control

When providing an LLM access to sensitive financial records, security is paramount. Truto provides several mechanisms to lock down your Ocrolus MCP servers:

• Method Filtering: Enforce read-only access. By setting config.methods: ["read"] during server creation, the MCP server will physically exclude all create, update, and delete tools from the tools/list response. The LLM cannot modify data, even if explicitly prompted to.
• Tag Filtering: Group tools by domain. You can restrict a server using config.tags: ["fraud_analysis"], ensuring the LLM only has access to specific endpoints and cannot query general organizational webhooks or user lists.
• Require API Token Auth: For shared environments, you can set require_api_token_auth: true. This forces the client connecting to the MCP URL to also supply a valid Truto API token in the Authorization header, adding a secondary layer of authentication beyond the URL token.
• Ephemeral Servers: By setting an expires_at timestamp, Truto automatically schedules a durable cleanup alarm. Once expired, the token is purged from distributed KV storage and the database, instantly revoking the LLM's access.

Final Thoughts

Connecting Ocrolus to ChatGPT using a managed MCP server transforms your LLM from a passive chat interface into an active participant in your underwriting and fraud detection pipeline. By offloading the authentication, tool generation, and schema normalization to Truto, your engineering team avoids writing and maintaining thousands of lines of integration code.

Instead of managing pagination cursors and OAuth refreshes, your team can focus on designing the system prompts that actually drive business value.