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.GETanswers 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_booksshows 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.
| Tool | What it does | Inputs | Writes |
|---|---|---|---|
list_books | Your sets of books Every set of books you can reach, with your role on each. | none | reads |
chart_of_accounts | Chart of accounts The accounts in a set of books: code, name and class. | tenantId string | reads |
trial_balance | Trial balance Every account's balance as at a day (today if none), in minor units. | tenantId stringasAt? stringcurrency? string | reads |
account_ledger | An account's entries One account's entries between two days, with opening, running and closing balances. Use this to search the ledger. | tenantId stringaccountCode stringfrom stringto string | reads |
review_queue | Waiting for a person Proposals waiting to be accepted or rejected, with their lines, confidence and the reasons they were proposed. | tenantId stringlimit? integer | reads |
profit_and_loss | Profit 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 stringfrom stringto stringcurrency? string | reads |
who_owes_you | Customers 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 string | reads |
bills_to_pay | Bills to pay Every unpaid supplier bill, oldest due first, with what is left to pay. | tenantId string | reads |
payables_aging | What the business owes, by age Money owed to suppliers per currency, by how long it has been due. | tenantId string | reads |
stock_on_hand | Stock on hand Each item: how many are held, what they cost, and the reorder level. | tenantId string | reads |
propose_journal | Propose 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 stringdate? stringmemo stringcurrency? stringlines array | proposes |
bank_reconciliation | Bank 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 stringaccountCode stringasOf? string | reads |
match_bank_line | Match 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 stringaccountCode stringlineIds arrayentryIds arraynote? 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_journalnever 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-RemainingandX-RateLimit-Reset(when the minute ends, in Unix seconds); a request over the limit is refused with429,Retry-AfterandretryAfterSeconds, 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.