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.
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
- Add the setup server shown below to your client.
- Copy the generated prompt and paste it into the agent. The agent calls
confirm_connectionwith the setup code. - 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.
Connect Claude
In Claude Code, register the server with this command. In Claude's connector settings, you can add the same URL as a custom connector.
claude mcp add --transport http openbooks-setup https://openbooks.lumeo.co.in/api/agent/mcp1. Install the local server
Download the Open Books MCP wheel · SHA-256 checksum
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.
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 --versionThe version command should print the installed server version. For scans or model checks, install the optional extras into the same environment.
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
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.
{
"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.
claude mcp add openbooks -- /absolute/path/.openbooks-mcp/bin/python -m openbooks_mcp --root /absolute/path/financial-inboxRestart 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
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
| 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
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.
{
"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
{
"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
| 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. |
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.
python -m openbooks_mcp --transport streamable-http
ssh -N -L 8791:127.0.0.1:8791 developer@your-vpsConfigure 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.