Connect Ocrolus to Claude: Automate Cash Flow & Risk Assessment

If you need to connect Ocrolus to Claude to automate cash flow analysis, evaluate self-employed income, or run risk assessments on bank statements, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and the Ocrolus REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Ocrolus to ChatGPT or explore our broader architectural overview on connecting Ocrolus to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling financial intelligence platform like Ocrolus is a significant engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas for cash flow features to MCP tool definitions, and deal with Ocrolus-specific asynchronous job polling. Every time Ocrolus updates an endpoint or changes an underwriting guideline parameter, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Ocrolus, connect it natively to Claude, and execute complex financial underwriting workflows using natural language.

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 the Ocrolus API requires handling strict financial data constraints and complex state machines.

If you decide to build a custom MCP server for Ocrolus, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous State Machines for Large Books Ocrolus processes documents in "Books". For small datasets, endpoints like ocrolus_cash_flow_get_features or ocrolus_transactions_list_enriched can return data synchronously. However, if a Book contains more than 100,000 transactions, the API strictly requires async=true (Books over 1,000,000 transactions are rejected outright). When forced into async mode, the API returns a job_id instead of the data. Your MCP server must then expose a polling mechanism (like ocrolus_cash_flow_get_job_status) so Claude can check the job status and eventually retrieve the presigned result URL. LLMs are notoriously bad at managing state; your integration layer has to clearly define these rules in the tool descriptions so the model knows when to wait.

Dual Identifier Collisions Many Ocrolus endpoints accept either a book_uuid (a string) or a pk (an integer primary key) to identify the target resource. These are strictly mutually exclusive. If you blindly expose both parameters to an LLM without strict JSON Schema validation, the model will frequently attempt to pass both, resulting in 400 Bad Request errors. A properly configured MCP server must use oneOf schema enforcement to prevent the LLM from hallucinating conflicting identifiers.

Strict Underwriting Enumerations When automating income verification via endpoints like ocrolus_income_calculate_self_employed_fm, Ocrolus requires strict adherence to underwriting guidelines (e.g., FANNIE_MAE, FREDDIE_MAC, FHA, VA, USDA). If the LLM generates "Fannie Mae" instead of the exact enum string, the request fails. Your MCP tool definitions must hardcode these allowed values into the parameter schemas.

Transparent Rate Limit Handling When processing hundreds of documents or polling for async job completion, you will inevitably hit Ocrolus rate limits. Truto's architectural stance on rate limits is pass-through visibility. Truto does not retry, throttle, or apply backoff automatically on rate limit errors. When Ocrolus returns an HTTP 429 Too Many Requests, Truto passes that exact error back to the caller (the LLM). Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - in this case, the agent framework - is responsible for reading the reset window and applying its own retry and backoff logic. This prevents your MCP server from hanging silently and eating up compute time.

How to Generate an Ocrolus MCP Server with Truto

Instead of building custom middleware to handle authentication, schema translation, and pagination, you can use Truto to generate a secure MCP server URL dynamically. This server exposes Ocrolus endpoints as ready-to-use JSON-RPC tools.

You can create this server through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Ocrolus account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods, or filter by specific tags like cash_flow).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz).

Method 2: Via the Truto API

For teams managing AI agents programmatically, you can generate MCP servers on the fly using the Truto API. This is ideal for multi-tenant applications where you need to spin up a temporary, scoped server for a specific user session.

// Example: Creating an Ocrolus MCP Server via API
const createMcpServer = async (integratedAccountId: string) => {
  const response = await fetch(
    `https://api.truto.one/integrated-account/${integratedAccountId}/mcp`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.TRUTO_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: "Ocrolus Cash Flow Agent Server",
        config: {
          // Restrict the LLM to specific functional areas
          methods: ["read", "create", "custom"],
          require_api_token_auth: false
        },
        // Auto-expire the server URL after 24 hours for security
        expires_at: new Date(Date.now() + 86400000).toISOString()
      })
    }
  );
 
  const data = await response.json();
  console.log(`Your MCP Server URL: ${data.url}`);
  return data.url;
};

The resulting URL encodes the integrated account context and authentication. When Claude makes a request to this endpoint, Truto dynamically fetches the integration's OpenAPI documentation, filters it based on your configuration, and translates it into MCP tool definitions on the fly.

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude environment. You can do this via the Claude interface or by modifying the configuration file directly.

Method A: Via the Claude UI

1. Open the Claude Desktop app or Web UI.
2. Navigate to Settings -> Integrations (or Connectors depending on your tier).
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP URL generated in the previous step.
5. Click Add. Claude will perform an initialization handshake, pull the available Ocrolus tools, and make them available to your agent immediately.

Method B: Via Manual Configuration File

If you are running Claude Desktop locally and prefer managing infrastructure as code, you can inject the server directly into your configuration file.

Locate your claude_desktop_config.json file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Truto server configuration using the standard SSE (Server-Sent Events) transport command:

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

Restart Claude Desktop. The agent will read the config and establish the JSON-RPC connection.

Ocrolus Hero Tools

Truto automatically maps the Ocrolus API into descriptive, snake_case tools that LLMs easily understand. Here are the most critical "hero tools" for automating financial analysis.

create_a_ocrolus_book

Books are the fundamental organizational unit in Ocrolus. Before you can analyze a bank statement or W-2, you must create a Book to hold those documents. This tool initializes that container.

Usage Note: The only required parameter is name. The API returns the book_uuid, which your agent must store and pass to subsequent document upload and analytics tools.

"Create a new Ocrolus book named 'Q3_Acme_Corp_Underwriting' so we can begin uploading their financial statements."

ocrolus_documents_upload_mixed_pdf

Uploading documents via API typically requires constructing raw multipart/form-data requests - a task LLMs cannot do natively. This tool accepts standard JSON arguments (including the file URL or base64 string depending on your proxy setup) and translates it into the precise binary format Ocrolus expects.

Usage Note: You must provide upload and book_uuid. Files are capped at 200 MB or 3000 pages.

"Upload the provided Plaid asset report PDF into the book with UUID 'b8f7x...' for mixed classification."

ocrolus_books_get_status

Because Ocrolus relies on ML and human-in-the-loop verification, processing is not instantaneous. This tool allows the LLM to check if a Book has finished processing before attempting to extract analytics.

Usage Note: The agent should be instructed to check this status and yield if the book is not yet 'COMPLETE'.

"Check the processing status for the Acme Corp book. If it's done, let me know; if not, I'll wait before running the cash flow features."

ocrolus_transactions_list_enriched

Once a book is processed, this tool returns the deduplicated, categorized transactions extracted from the uploaded bank statements. It provides enrichment tags, specific transaction categories, and counterparty identification.

Usage Note: For books with > 100,000 transactions, the agent must include async=true and be prepared to receive a job_id instead of raw transaction data.

"Pull the enriched transaction list for the verified Acme Corp book so I can look for recurring subscriptions and unknown counterparties."

ocrolus_cash_flow_get_risk_score

This tool triggers Ocrolus's proprietary cash flow risk analytics against the entire set of bank statements within a Book. It evaluates cash buffers, overdraft frequencies, and revenue stability.

Usage Note: Risk scoring must be enabled on your Ocrolus organization account. Like transactions, massive books require async polling.

"Generate the cash flow risk score for this applicant's book to see if their overdraft history disqualifies them for the tier 1 loan."

ocrolus_income_calculate_self_employed_fm

Automates the complex task of calculating qualifying income for self-employed borrowers using official Fannie Mae guidelines. It requires the agent to pass specific borrower and business metadata alongside the book ID.

Usage Note: The income_guideline parameter defaults to FANNIE_MAE but requires strict enum validation if altered.

"Calculate the self-employed income for the borrower in this book using standard Fannie Mae guidelines and summarize their monthly qualifying income."

ocrolus_cash_flow_get_job_status

When a book crosses the 100,000 transaction threshold, analytics tools return a job_id. The agent must use this tool to poll the status of that asynchronous job until it returns a presigned result URL.

Usage Note: Agents should be prompted to wait a reasonable interval (e.g., 30 seconds) between polling attempts to avoid hitting rate limits.

"Check the status of job ID 'job_99823'. If it is complete, fetch the results from the presigned URL."

For the complete inventory of available Ocrolus tools - including webhook configuration, tag management, and Plaid asset report imports - see the Ocrolus integration page.

Workflows in Action

Here is how an LLM uses these tools to execute complex financial workflows autonomously.

Scenario 1: Automated Self-Employed Income Verification

A mortgage underwriter needs to verify the income of a self-employed applicant using Fannie Mae guidelines based on newly uploaded tax returns and bank statements.

"The applicant's documents have been uploaded to book 'bk_77492'. Check if the book is done processing. If it is, run the self-employed income calculation using Fannie Mae guidelines and give me a summary of their qualifying monthly income."

Execution Steps:

1. Claude calls ocrolus_books_get_status with book_uuid: "bk_77492".
2. The API returns status: "COMPLETE".
3. Claude calls ocrolus_income_calculate_self_employed_fm passing the book_uuid and defaulting to the Fannie Mae enum.
4. Claude parses the returned JSON payload and outputs a natural language summary of the borrower's qualifying income, highlighting any anomalous deductions found by the ML models.

Scenario 2: Large-Scale Cash Flow Risk Assessment

A commercial credit analyst needs to evaluate a massive corporate account with over 150,000 transactions across dozens of linked bank statements.

"Run the cash flow features and risk score for the corporate book 'bk_99321'. Since this is a massive file, use async mode and poll until the results are ready. Summarize the major risk factors."

sequenceDiagram
    participant Claude as Claude Desktop
    participant Proxy as Truto MCP Server
    participant Ocrolus as Ocrolus API

    Claude->>Proxy: Call ocrolus_cash_flow_get_risk_score(book_uuid, async: true)
    Proxy->>Ocrolus: POST /v1/books/bk_99321/analytics/risk
    Ocrolus-->>Proxy: 202 Accepted (job_id: "job_444")
    Proxy-->>Claude: Returns job_id
    
    Note over Claude,Ocrolus: Agent waits based on prompt instructions
    
    Claude->>Proxy: Call ocrolus_cash_flow_get_job_status("job_444")
    Proxy->>Ocrolus: GET /v1/jobs/job_444
    Ocrolus-->>Proxy: 200 OK (status: "PROCESSING")
    Proxy-->>Claude: Returns status: PROCESSING
    
    Note over Claude,Ocrolus: Agent waits again
    
    Claude->>Proxy: Call ocrolus_cash_flow_get_job_status("job_444")
    Proxy->>Ocrolus: GET /v1/jobs/job_444
    Ocrolus-->>Proxy: 200 OK (status: "COMPLETE", result_url: "https...")
    Proxy-->>Claude: Returns presigned URL

Execution Steps:

1. Claude triggers the risk score tool, explicitly setting async=true.
2. The tool returns a job_id.
3. Claude loops, calling ocrolus_cash_flow_get_job_status.
4. Once complete, Claude extracts the data from the presigned URL and summarizes the cash buffers and overdraft risks for the analyst.

Security and Access Control

Exposing financial records and PII to an LLM requires strict governance. Truto's MCP servers provide several layers of access control out of the box:

• Method Filtering: You can restrict a server to only perform read operations (e.g., methods: ["read"]). This allows Claude to query cash flow analytics and risk scores without the ability to accidentally delete books or alter underwriting configurations.
• Tag Filtering: Limit the LLM's scope by functional area. For example, setting tags: ["cash_flow", "income"] ensures the agent only sees tools relevant to financial analysis, hiding webhook management and administrative endpoints.
• Enforced Expiration (expires_at): You can generate ephemeral MCP servers for temporary workflows. If a contractor needs to run an audit, set an expiry timestamp; Truto's managed storage automatically purges the authentication token when the time is up.
• Secondary Authentication (require_api_token_auth): For maximum security, you can configure the MCP server to require a valid Truto API token in the Authorization header, meaning possession of the MCP URL alone is not enough to execute calls.

Moving Past Manual Integrations

Building an AI agent that can reliably parse financial documents, handle async analytics jobs, and accurately extract risk scores shouldn't require weeks of integration boilerplate. The Ocrolus API is powerful, but navigating its dual identifiers, multipart form requirements, and strict pagination rules distracts your engineering team from building actual AI features.

By utilizing Truto's dynamically generated MCP servers, you offload the authentication, schema mapping, and protocol translation. Your agents get immediate, secure access to the financial intelligence they need, and your engineers get to focus on core product value.