# MCP for AI agents

Download and install the Open Books Model Context Protocol server to verify financial files with an AI agent and inspect the evidence in one batched call.

Source: https://openbooks.lumeo.co.in/docs/mcp

Model Context Protocol (MCP) lets an AI client call tools supplied by another program. The Open Books MCP server lets a compatible client run the Python engine and retrieve decisions, records, and proof for financial files. Choose the setup path that matches what you want to do.

| Goal | Start here |
| --- | --- |
| Verify that your client can connect | Use the connection test below. |
| Process files from a folder you control | Install the local server and connect over stdio, where the client starts the server as a subprocess. |
| Send uploads to a private shared server | Use Streamable HTTP with a bearer token. |

## Test your client's connection [#test-your-clients-connection]

1. Add the setup server shown below to your client.
2. Copy the generated prompt and paste it into the agent. The agent calls `confirm_connection` with the setup code.
3. Watch for confirmation on this page. If the code expires after ten minutes, generate a fresh code.

The setup endpoint confirms connectivity. Install the full server to process financial files.

<AgentOnboarding />

## 1. Install the local server [#1-install-the-local-server]

[Download the Open Books MCP wheel](/downloads/openbooks_mcp-0.1.0-py3-none-any.whl) · [SHA-256 checksum](/downloads/openbooks_mcp-0.1.0-py3-none-any.whl.sha256)

Use Python 3.11 or newer. Create a virtual environment and install the downloaded wheel, or use the release URL in the command below. A wheel is a packaged Python distribution.

~~~bash
python -m venv .openbooks-mcp
# macOS and Linux
source .openbooks-mcp/bin/activate
# PowerShell uses: .\.openbooks-mcp\Scripts\Activate.ps1
python -m pip install https://openbooks.lumeo.co.in/downloads/openbooks_mcp-0.1.0-py3-none-any.whl
python -m openbooks_mcp --version
~~~

The version command should print the installed server version. For [scans or model checks](/docs/pdf-and-ocr), install the optional extras into the same environment.

~~~bash
python -m pip install "openbooks-mcp[scan] @ https://openbooks.lumeo.co.in/downloads/openbooks_mcp-0.1.0-py3-none-any.whl"
~~~

## 2. Connect an MCP client [#2-connect-an-mcp-client]

Create a dedicated directory for inputs and put a synthetic file there for your first run. For clients that use an `mcpServers` configuration, replace both absolute paths in the following example. Point `command` to the virtual environment's Python and `--root` to your existing input folder. On Windows, the interpreter is under `Scripts/python.exe`. You can use forward slashes in JSON paths, for example `C:/Projects/.openbooks-mcp/Scripts/python.exe`.

~~~json
{
  "mcpServers": {
    "openbooks": {
      "command": "/absolute/path/.openbooks-mcp/bin/python",
      "args": ["-m", "openbooks_mcp", "--root", "/absolute/path/financial-inbox"]
    }
  }
}
~~~

For Claude Code, register the same launch command.

~~~bash
claude mcp add openbooks -- /absolute/path/.openbooks-mcp/bin/python -m openbooks_mcp --root /absolute/path/financial-inbox
~~~

Restart the MCP client and check that it lists `search` and `execute`. Start with the synthetic sample. Omit `--root` to use just samples and uploaded bytes. The MCP client may send tool responses to its model provider. Check your client's data settings before exposing financial records.

## 3. Discover and run operations [#3-discover-and-run-operations]

`search` returns operation names and descriptions for a keyword. For example, send `{"query":"sample","details":true}` to get the operation and its argument schema. Then pass named steps to `execute`. A step that retrieves records points to a preceding processing step by ID. This follows a discovery-and-execution pattern. [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/)

| Operation | What it returns |
| --- | --- |
| `formats` | Installed layouts, supported extensions, engine contract and file limits. |
| `process_sample` | Release or refusal summary for a synthetic bank CSV. |
| `process_file` | A decision for a path relative to the approved local folder. Available with `--root` over stdio. |
| `process_upload` | A decision for up to 1 MiB of standard base64 file bytes. |
| `records` | A page of the specified collection from an earlier successful processing step. |
| `document` | The entire release or refusal document from an earlier processing step, subject to the response limit. |

### Process and inspect a statement in one call [#process-and-inspect-a-statement-in-one-call]

Send these arguments to `execute`. It processes two versions of the sample and reads the released batch balance and verification assertions in the same call.

~~~json
{
  "steps": [
    { "id": "missing", "operation": "process_sample" },
    { "id": "statement", "operation": "process_sample", "arguments": { "opening": "1000.00" } },
    { "id": "balance", "operation": "records", "arguments": { "from_step": "statement", "collection": "batches" } },
    { "id": "checks", "operation": "records", "arguments": { "from_step": "statement", "collection": "assertions" } }
  ]
}
~~~

The first outcome is a `PARSE_ERROR` refusal. The second releases two transactions and the balance record shows a `950.00` INR closing amount. Each successful processing operation starts with a compact summary. Use `records` with `offset` and `limit` to retrieve only the needed items. For evidence, use `prefix` to match a record ID such as `txn-00001.`.

### Process a local export [#process-a-local-export]

~~~json
{
  "steps": [
    {
      "id": "bank",
      "operation": "process_file",
      "arguments": { "path": "january.csv", "currency": "INR", "opening": "1000.00", "date_order": "dmy" }
    },
    {
      "id": "rows",
      "operation": "records",
      "arguments": { "from_step": "bank", "collection": "transactions", "limit": 5 }
    }
  ]
}
~~~

One batch accepts up to eight uniquely named steps. Documents referenced by `from_step` are held for the current batch. Results retain the engine's exact decimal strings. A document refusal appears inside a result. An operation error such as `INVALID_PATH` or `RESPONSE_LIMIT` appears as an error on the affected step. HTTP uses a 2 MiB request limit and batched output is bounded to 48 KiB.

## Troubleshoot a connection or tool call [#troubleshoot-a-connection-or-tool-call]

| Symptom | Check |
| --- | --- |
| The client cannot start the server | Run the configured interpreter with `-m openbooks_mcp --version` and verify that the client config points to that interpreter. |
| The client lists tools but `process_file` is missing | Use stdio with an existing directory passed to `--root`. |
| `INVALID_PATH` | Pass a path relative to the approved folder, such as `january.csv`. |
| `RESPONSE_LIMIT` | Use `records` with a smaller `limit` instead of retrieving the entire document. |
| The document returns `PARSE_ERROR` | Read the document's message and follow the [refusal guide](/docs/refusals). |

## Private HTTP transport [#private-http-transport]

Use Streamable HTTP for an organisation-managed service. Run it with `OPENBOOKS_MCP_TOKEN` set to a high-entropy secret. It listens on loopback, requires that token as an `Authorization: Bearer …` header, and supports in-memory uploads and the synthetic sample. Connect using a private SSH tunnel or an authenticated TLS gateway managed by your organisation.

~~~bash
python -m openbooks_mcp --transport streamable-http
ssh -N -L 8791:127.0.0.1:8791 developer@your-vps
~~~

Configure the MCP client for Streamable HTTP at `http://127.0.0.1:8791/mcp` and supply the bearer token via its secret store. The base installation handles structured files and text-layer PDFs. The local engine's `scan` extra adds the OCR and model runtime on deployments where those resources are available.
