Ask Claude about your books
A connected assistant reads your real ledger through MCP. Press play and send the question yourself.
Connect AI Assistants to Ringbook
The Ringbook MCP server connects Claude — through claude.ai custom connectors, Claude Desktop, Claude Code, or Cursor — or any other MCP-compatible client directly to your organization's accounting data. Ask a question in plain language and your assistant reads your ledger, chart of accounts, documents, and reports to answer it.
MCP (the Model Context Protocol) is an open standard for exposing tools and data to AI assistants. Ringbook implements it as a hosted remote server, so there is nothing to install or run yourself: you authorize a connection, choose which organizations it can see and at what level, and your client discovers the available tools automatically.
The demo above is the whole idea in one screen — you ask, the assistant picks a Ringbook tool on its own, and the answer comes back with figures out of your books instead of a guess.
There are two ways to connect, and both are governed by the same access rules:
- OAuth custom connector — on claude.ai and Claude Desktop, click connect and sign in to Ringbook. On the consent screen you pick exactly which organizations the connection can reach and the access level for each. Best for everyday use — no secrets to copy or store.
- Personal access token — for developer tools and clients that take a bearer token. Create a token in-app and choose the organizations and per-organization level it carries. Best for Claude Code, Cursor, scripts, and CI.
Contents
- 1. What you can ask
- 2. Connect Claude (claude.ai / Claude Desktop)
- 3. Connect developer tools (personal access token)
- 4. Available tools
- 5. Writes are drafts — a human stays in the loop
- 6. Security model
- 7. Credits and rate limits
- 8. FAQ
1. What you can ask
Once connected, ask your assistant the things you would otherwise go digging for:
- "Summarize my P&L for last quarter."
- "Find all invoices from vendor X."
- "Which expense account grew the most this year?"
- "Show me anything that looks like an unpaid payable."
- "Which bank accounts still have unmatched statement lines?"
Answers come from the organizations you granted, and only from those: the ledger, the chart of accounts, financial reports, uploaded documents, open items, and bank-reconciliation status. Every figure is read live at the moment you ask.
2. Connect Claude (claude.ai / Claude Desktop)
This is the recommended path for claude.ai and Claude Desktop. There are no tokens to copy — you sign in and consent.
- Open Settings → Connectors and choose Add custom connector.
- Enter the server URL:
https://backend.ringbook.io/mcp - Sign in to Ringbook when prompted.
- On the consent screen, choose which organizations to share and the access level (Reports, Read, or Write) for each, then approve.
You can re-open the consent screen later to change which organizations are shared or adjust levels.
Generally available. OAuth connect is live — Add custom connector works for claude.ai and Claude Desktop today. Sign in and consent; there is no token to copy. For Claude Code, Cursor, scripts, or any client that takes a bearer header, the personal access token path below works everywhere too.
Connect Claude with OAuth
The consent screen decides exactly which organizations Claude can see — walk through it. Press the highlighted controls yourself.
3. Connect developer tools (personal access token)
For Claude Code, Cursor, scripts, or any client that accepts a bearer token, create a personal access token in the app:
- Go to the Connect to Ring page in Ringbook.
- Create a token.
- Choose which organizations it can reach and the level per organization.
- Copy the token (it starts with
rb_mcp_) — it is shown only once.
Create a personal access token
For Claude Code, Cursor, and scripts — mint a scoped token in the app. Follow the prompts — press the highlighted controls yourself.
Create a token to let an AI agent read your Ringbook data and stage draft entries.
https://backend.ringbook.io/mcpThen wire it into your client:
https://backend.ringbook.io/mcpClaude Code
claude mcp add --transport http ringbook https://backend.ringbook.io/mcp \
--header "Authorization: Bearer rb_mcp_..."Claude Desktop / Cursor / generic MCP clients
Add this to the client's MCP configuration (in Cursor, the MCP integrations settings). Replace the token with your own:
{
"mcpServers": {
"ringbook": {
"url": "https://backend.ringbook.io/mcp",
"headers": {
"Authorization": "Bearer rb_mcp_..."
}
}
}
}curl (verify a token)
A raw JSON-RPC call that lists the tools available to your token. Streamable HTTP requires both content types in the Accept header:
curl -N https://backend.ringbook.io/mcp \
-H "Authorization: Bearer rb_mcp_..." \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'4. Available tools
Read tools answer straight out of your books. Write tools stage drafts for a person to review and require a Write-level grant.
| Tool | What it does | Min level | Status |
|---|---|---|---|
| list_organizations | List the organizations this connection can reach, with your access level for each. | Reports | Live |
| get_organization_info | Fetch an organization's profile: name, currency, fiscal settings. | Reports | Live |
| generate_report | Balance sheet, profit & loss, or trial balance — with optional per-account detail (includeAccounts). | Reports | Live |
| export_report | Download a balance sheet, profit & loss, or trial balance as a CSV or XLSX file — full per-account detail with category subtotals and the statement summary. | Reports | Live |
| export_report_pdf | Render a balance sheet, profit & loss, or trial balance as a formatted PDF and return a short-lived (about 5 minutes) download link. The file is not saved to your shoebox. | Reports | Live |
| get_job_status | Check the progress of a long-running background job. | Reports | Live |
| list_accounts | List the chart of accounts. Use it to find account ids before filtering transactions. | Read | Live |
| search_transactions | Search and filter journal transactions by date, account, amount, and text. | Read | Live |
| get_transaction | Read one transaction in full, including its lines and attachments. | Read | Live |
| export_transactions | Download transactions as a CSV or XLSX file — one row per journal line with account, debit/credit, currency, and creator (up to 5,000 rows). | Read | Live |
| search_documents | Search uploaded documents (invoices, receipts, statements) by their extracted contents. | Read | Live |
| get_document | Fetch a short-lived (about 5 minutes) download link for a document found via search_documents. | Read | Live |
| get_credit_balance | Check the organization's remaining credit balance before calling a billable tool. Free. | Read | Live |
| list_open_items | List open receivables or payables per counterparty — remaining amounts, due dates, and aging buckets. | Read | Live |
| get_reconciliation_summary | Bank-reconciliation status per account: book vs statement balance, matched and unmatched counts, last reconciled date. | Read | Live |
| get_statement_lines | Show the extracted statement table for a reconciliation session — the parsed bank rows, paginated — so a parse can be reviewed before reconciling. | Read | Live |
| list_reconciliation_matches | Drill into one reconciliation session: which journal entries were matched, and whether the AI or a person matched them. | Read | Live |
| list_discrepancies | Drill into one reconciliation run: the statement lines and ledger entries that could not be matched, each with its type and the AI's proposed account. Read-only — resolving an item stays in the app. | Read | Live |
| list_unlinked_documents | List documents not yet attached to anything (no transaction, journal entry, ring, or reconciliation), with stored candidate matches and confidence. | Read | Live |
| create_transaction | Stage a journal entry as a DRAFT for a human to review. Organization admins can optionally enable automatic posting of balanced entries in organization settings; drafts are the default. | Write | Live |
| create_account | Create a new account in the chart of accounts (name, type, category, normal balance, optional grouping levels). The currency must be the organization's base currency or "ANY"; omit the code to auto-generate the next free one. | Write | Live |
| create_ring | Create a ring (a grouped set of related items) as a draft for review. | Write | Live |
| start_statement_extraction | Kick off extraction of a bank/credit-card statement into draft transactions. Extracting a PDF or image statement costs 50 credits; spreadsheet/CSV statements are usually free. | Write | Live |
| start_reconciliation | Kick off AI reconciliation of an already-extracted bank statement against the ledger for one account — matching statement lines to journal entries and flagging discrepancies for human review (150 credits, billed when the job runs). | Write | Live |
| upload_document | Mint a signed upload URL so a document (invoice, receipt, statement) can be added to the organization's shoebox. | Write | Live |
| finalize_document_upload | Register a document that was PUT to a signed upload URL, making it searchable. Completes the two-step upload. | Write | Live |
| generate_journal_from_document | Have Ringbook's own AI draft a journal entry from an uploaded document, for a human to review. Costs 50 credits. | Write | Live |
A few tools consume organization credits (never your personal balance): search_documents costs 10, generate_journal_from_document costs 50, and start_statement_extraction costs 50 for a PDF or image statement (spreadsheet/CSV statements are usually free). Most other tools are free — the exception is that a confident background auto-match when a document is ingested (for example via finalize_document_upload) can incur an automatch charge of about 30 credits. Failed calls are refunded, and get_credit_balance lets an agent check affordability first.
5. Writes are drafts — a human stays in the loop
Agent writes become drafts
A write-enabled agent stages entries; a person reviews and posts. Try the whole loop.
Ringbook is connected with a Write grant. Ask in plain language — the agent picks the tools itself.
An agent with write access cannot post to your ledger. Its entries are staged as drafts for a person to review and post — that is the default for every organization, and it is the loop the demo above walks through.
An organization admin can explicitly opt in to automatic posting of balanced entries in organization settings. Even then, an agent's entry passes exactly the same validation a human entry does, and agents can still never modify or delete existing entries.
6. Security model
Because this connects an AI assistant to your books, security is the starting point, not an afterthought. Whichever way you connect, the same rules apply.
Per-organization access levels. Every connection carries a level for each organization it can reach. Levels are cumulative — each one includes everything below it:
| Level | What it covers |
|---|---|
| Reports | Financial reports only — balance sheet, P&L, trial balance, and basic organization info. |
| Read | Everything in Reports, plus read access to all data: transactions, accounts, and documents. |
| Write | Everything in Read, plus the ability to stage drafts for a human to review. Granting write on either a personal access token or an OAuth connection requires organization-admin rights (org_settings:manage). |
Your live access rights always win. Effective access is always the minimum of the level you granted and your live, in-app access rights. If you lose membership of an organization, or an admin narrows your rights, the connection's access to that organization narrows or closes immediately — a granted token can never exceed what you yourself can do in the app right now.
Credential handling.
- Tokens are hashed at rest and shown in full exactly once, at creation — store it somewhere safe.
- Every token must expire; there are no immortal tokens. Expiry defaults to 90 days and cannot be set beyond 1 year. It is fixed at creation and cannot be extended by editing — to re-clock it, revoke the token and create a fresh one.
- A token can optionally carry a tool allowlist (least privilege — restrict it to just the tools it needs). You can also edit a token in-app to rename it, adjust its organizations and levels, or change its allowlist; the secret and the expiry are immutable.
- Organization admins have a kill switch: they can revoke any credential's access to their organization at any time.
7. Credits and rate limits
A few tools consume organization credits; your personal balance is only ever touched if the organization falls short and you have enabled personal-credit fallback in your profile:
search_documents— 10 credits.generate_journal_from_document— 50 credits.start_statement_extraction— 50 credits for a PDF or image statement; spreadsheet and CSV statements are usually free.start_reconciliation— 150 credits, billed when the job runs.
Most other tools are free. The one exception to watch: a confident background auto-match when a document is ingested (for example via finalize_document_upload) can incur an automatch charge of about 30 credits. Failed calls are refunded, and get_credit_balance is free, so an agent can check affordability before it spends anything.
Requests are also rate-limited per token and per organization to keep the service responsive. Well-behaved interactive use will not normally hit those limits.
8. FAQ
Can one connection reach several organizations? Yes. A single connection or token can be granted access to multiple organizations, each with its own level. Use list_organizations to see what a connection can reach.
How do I revoke access? Two ways. Self-service: delete the token or connection from your own settings. Organization admins can also revoke any credential's access to their organization at any time — the kill switch. And because effective access is the minimum of the grant and your live rights, removing membership or narrowing rights closes access immediately too.
Will tool schemas change under my agent? Tool schemas evolve additively only: new tools, new optional parameters, and new response fields may appear, but existing tools, parameters, and response fields are never renamed, removed, or made stricter. If a breaking change is ever needed, a versioned replacement (for example search_transactions_v2) ships alongside the old tool, which keeps working for at least 90 days.
What can agents not do? Three hard limits:
- They cannot delete anything.
- They cannot see or touch any organization, or any data, beyond your own access rights.
- They cannot post to the ledger by default — write tools stage drafts for a person to review. An organization admin can explicitly opt in to automatic posting of balanced entries in organization settings; even then, entries pass the same validation a human entry does, and agents can still never modify or delete existing entries.