Developers

Build on the books.

An agent, Claude or any client that speaks the Model Context Protocol, can read a set of books and propose entries as the person who let it in. It never posts: a person, or a rule a person set, decides.

Connecting

  • Endpoint: POST https://api.thumabooks.com/api/v1/mcp. Streamable HTTP, stateless, JSON responses. GET answers 405: there is no server-initiated stream.
  • Authentication: Authorization: Bearer <the person's Thuma access token>, exactly as every other route. No token: 401.
  • Protocol versions: 2025-06-18 (preferred), 2025-03-26, 2024-11-05.

An agent token, for an agent that runs on its own

Access tokens last minutes. For an agent left running, make an agent token on the Desk (Modules → Agent tokens) and connect to the agent door:

  • Endpoint: POST https://api.thumabooks.com/api/v1/mcp/agent, the same server and tools.
  • Authentication: Authorization: Bearer tbk_… (an agent token, shown once). The agent door takes nothing else, and no other route takes an agent token.
  • Narrower than its person, never wider:
  • it acts as the person who made it, with the access they have on the day it is used (lose a role, and the token loses it too);
  • it reads, or reads and proposes: a read-only token is shown only the reading tools, and a write is refused with a sentence;
  • it may be held to one set of books: list_books shows only that one, and any other is refused;
  • it expires (30, 90 or 365 days; never more than a year) and is revoked with one press, at once.
  • Kept as its SHA-256 only, and kept after it is revoked or expires (migration 535): who could act as whom, until when. At most ten live at once.

A sandbox to try it on

No books to point an agent at? Make a sandbox on the Desk (Agent tokens), or POST /api/v1/books-agent-tokens/sandbox with your session: one set of books per person, called Sandbox books, with sample customers and sales (paid and owed), supplier bills and a journal waiting in the review queue, put in through the same services real books use. Make a token held to it. A sandbox never reaches outside the books: it registers no fiscal device and sends no payment reminders; and it stays a sandbox (migration 536).

curl https://api.thumabooks.com/api/v1/mcp/agent \
  -H 'Authorization: Bearer tbk_…' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_books","arguments":{}}}'

The tools

Amounts are whole minor units (cents). A refusal comes back as the books' own sentence, as a tool error an agent can read.

ToolWhat it doesInputsWrites
list_booksYour sets of books
Every set of books you can reach, with your role on each.
nonereads
chart_of_accountsChart of accounts
The accounts in a set of books: code, name and class.
tenantId stringreads
trial_balanceTrial balance
Every account's balance as at a day (today if none), in minor units.
tenantId string
asAt? string
currency? string
reads
account_ledgerAn account's entries
One account's entries between two days, with opening, running and closing balances. Use this to search the ledger.
tenantId string
accountCode string
from string
to string
reads
review_queueWaiting for a person
Proposals waiting to be accepted or rejected, with their lines, confidence and the reasons they were proposed.
tenantId string
limit? integer
reads
profit_and_lossProfit and loss
Income, cost of sales, expenses and profit between two days, in minor units of one currency (the books' own if none is named).
tenantId string
from string
to string
currency? string
reads
who_owes_youCustomers who owe
Customers with money still owing: how much, since when, and how much of it is past due by 30, 60 and 90 days.
tenantId stringreads
bills_to_payBills to pay
Every unpaid supplier bill, oldest due first, with what is left to pay.
tenantId stringreads
payables_agingWhat the business owes, by age
Money owed to suppliers per currency, by how long it has been due.
tenantId stringreads
stock_on_handStock on hand
Each item: how many are held, what they cost, and the reorder level.
tenantId stringreads
propose_journalPropose a journal
Propose a balanced journal. It is never posted by this tool: it waits in the review queue, in your name, until somebody accepts it. Amounts are whole minor units (cents); each line is a debit or a credit.
tenantId string
date? string
memo string
currency? string
lines array
proposes
bank_reconciliationBank reconciliation
A bank or wallet account against its statements: the difference, the statement lines not in the books and the postings not on the statement, with the ids match_bank_line takes.
tenantId string
accountCode string
asOf? string
reads
match_bank_lineMatch a bank line
Say that bank statement line(s) and posting(s) are the same money. Nothing is posted; the reconciliation stops listing them. Undone on the Desk.
tenantId string
accountCode string
lineIds array
entryIds array
note? string
proposes

Listed from the server's own tool list; a ? marks an optional input.

The rules it keeps

  • As its person, exactly. Each tool calls the same service method as the matching route, with the caller as the actor: a viewer's agent reads and cannot propose; a closed period refuses a journal; four eyes hold; read-only books stay read-only; books the person cannot see do not exist.
  • The model proposes, the ledger disposes. propose_journal never posts, however small: the entry waits in the review queue in the person's name, marked "proposed through the ThumaBooks MCP server". Posting it is a person's decision, or the business's own routing — and a person's journal is never auto-posted by confidence.
  • Refusals are sentences. A refused call returns the books' own sentence as a tool error (isError: true), which an agent can read and act on.
  • At most 120 requests a minute from one address, on every route of the API, the MCP server's included. Every answer says where the caller stands in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (when the minute ends, in Unix seconds); a request over the limit is refused with 429, Retry-After and retryAfterSeconds, and nothing in it happens, so it is safe to send again once that time has passed.

Building something?

Tell us what, and we will help: support@thumabooks.com.