Safety Model

Safety model #

Books are records you answer for — to partners, auditors and tax authorities. The MCP server is therefore designed so that an assistant can be useful without ever being able to silently damage the ledger.

Drafts, then an explicit commit #

Every recording tool creates a transaction in the pending state. Pending drafts can be edited or discarded freely and are invisible to reports. Only post_transaction moves a draft to the ledger, and its description warns the assistant that posting is irreversible — a posted transaction is immutable and can only ever be corrected by a reversing entry.

This mirrors the platform’s own two-step commit, so the assistant works the way a bookkeeper does: draft, review, post.

Dry runs everywhere #

All writes — recording, posting, reconciling — accept dry_run=true. The server sends the books API’s rollback header, so the operation is validated by the real API and then rolled back, and the assistant can show you exactly what would happen before doing it.

Read-back verification #

An autonomous agent cannot correct itself after a response that reports success, so the server checks its writes at every layer:

  • Tool arguments are strictly validated: unknown or misspelled arguments are rejected rather than dropped.
  • The books API itself rejects unknown fields with a 422 naming every field it would have accepted, so a typo is never reported as success and the assistant is told how to fix it.
  • After every real write the server re-reads the record and compares it field by field with what was sent — the transaction header, its line items, the amounts and quantities, and whether the taxes and discounts actually landed. The result carries a verification block, and the assistant is instructed to treat the write as successful only when verification.verified is true.
  • After posting, it additionally confirms is_posted is actually true, instead of trusting the write response.

Setup tools verify the same way: a created or updated account, tax or currency is read back and compared before the tool reports success.

verified: false is not a failure you can ignore. It means the API accepted the request and stored something else. The mismatches name the fields, and the right response is to stop and reconcile rather than carry on.

Human-in-the-loop posting #

Set MICROBOOKS_CONFIRM_POST=1 and the server asks you — through the MCP client, not the model — to confirm every non-dry-run post before it happens. See Configuration.

Two operations ask regardless of that setting, because each is larger than posting a single transaction:

  • post_period_close, which commits a whole reporting period’s closing transactions;
  • destroy_recycled, which deletes a recycled resource permanently and additionally makes you name what you are destroying.

If your client cannot show a prompt, these fail with an explanation rather than proceeding unconfirmed.

What the assistant cannot reach #

The surface is deliberately smaller than the API:

  • Posted transactions are immutable. amend_draft refuses one locally, before any request is sent, and tells the assistant to use a credit note, debit note or journal entry instead.
  • Period close, the recycle bin and chart-of-accounts setup are off by default, and invisible while off.
  • Nothing reaches your account, apps or tokens — the token carries only books:read and books:write.

Scoped, revocable credentials #

The recommended setup authenticates with a personal access token carrying only books:read/books:write. It cannot manage your account, OAuth apps or other tokens, and you can revoke it at any moment from Dashboard → Developers → API tokens — the connection dies immediately.