How CosBooks works: double-entry accounting that lives inside Claude

Most accounting software asks you to translate what happened in your business into its user interface: find the customer record, open the invoice form, pick the line items, choose an income account, save. CosBooks removes that translation step. You describe what happened, and a real double-entry ledger records it.

This post is the honest, mechanical version of how that works — what the AI decides, what it emphatically does not decide, and where your numbers actually live.

The one-sentence version

CosBooks is a Model Context Protocol (MCP) server: a program that exposes a catalogue of typed tools to an AI assistant. Claude reads your sentence, picks a tool, and calls it with structured arguments. CosBooks validates those arguments, writes balanced journal entries to Postgres inside a single transaction, and hands back a result the assistant reads aloud.

The assistant is the interface. The accounting rules are code.

Following one sentence all the way down

Take a concrete request: “Invoice Widget Co for 10 hours of consulting at $150 an hour, due in 30 days.” Five things happen.

1. 01

   Tool selection

   Claude sees a catalogue of 50+ tools with descriptions and JSON schemas — cosbooks_create_invoice, cosbooks_record_payment, cosbooks_profit_loss and so on. It picks the invoice tool and fills the schema: customer name, line items, quantity, rate, due date.

2. 02

   Identity resolution and guards

   Before anything is written, every caller-supplied id is resolved against your organization. “Widget Co” has to match a customer that belongs to you; an account id has to be your account. An id that fails this check never reaches the SQL layer.

3. 03

   Double-entry posting

   The invoice is written together with its journal entry: Accounts Receivable is debited $1,500, consulting revenue is credited $1,500, and any tax code splits out to its own liability line. The entry is checked for balance before it commits — debits must equal credits, exactly, in integer cents.

4. 04

   One transaction, all or nothing

   The invoice, its line items, the journal entry and the audit record commit together. If any part fails — an unbalanced entry, a customer that is not yours, a bad tax code — the whole call rolls back and the tool returns an error instead of a half-written invoice.

5. 05

   A readable answer

   Claude reports what it recorded: invoice number, total, due date, and the accounts touched. Your next question — “what do they owe me now?” — hits the same ledger.

Notice which step the model owns. It owns step one: understanding the sentence and choosing the tool. Steps two through four are ordinary, deterministic server code, and they run identically whether the caller is Claude, a script, or a test.

Why double-entry still matters when an AI is driving

It would be easy to build an “AI bookkeeper” as a list of transactions with a category attached to each. That version demos beautifully and falls apart at tax time, because there is no structural check on whether the books are internally consistent.

Double-entry gives you that check for free. Every transaction moves value between two or more accounts, and the sum of debits must equal the sum of credits. Run a trial balance and either it balances or something is wrong — a question no single-entry system can even ask.

That property is exactly what you want when a language model is generating the inputs. The model can be wrong about which account an expense belongs to, and you can fix that with a reclassification entry. The model cannot make the books stop balancing, because it never writes the entry — it only supplies the arguments to code that does.

The model chooses the tool. The ledger enforces the rules. Those two jobs never swap.

What the ledger can actually do

CosBooks covers the operational core of a small-business accounting system — the same ground a QuickBooks or Xero subscription covers, minus the screens.

One design decision is worth calling out: invoices post to the books the moment they are created. There is no draft limbo where a document exists but the ledger does not know about it. If Claude tells you an invoice exists, your AR balance already reflects it.

How the AI part learns

Categorization is the one place where CosBooks genuinely improves with use. When you import a bank statement and confirm that “AWS 449.20” belongs in Software & Hosting, that decision is stored as a rule. The next statement categorizes it automatically, with the rule — not the model — doing the work.

• Categorization suggestions come from rules learned out of your own matching history, so they reflect your chart of accounts rather than a generic one.
• Anomaly detection flags transactions that are unusual against your history — a spending spike, a duplicate-looking payment, a vendor charging several times the usual amount.
• Suggestions surface the boring-but-valuable items: invoices aging past terms, an account that has drifted well over budget, a recurring bill that did not arrive this month.

Everything a suggestion touches is still posted through the same guarded, balanced, audited path as anything else.

Isolation, roles and the audit trail

Multi-tenancy is enforced in layers, in the order they bite. Every query carries your organization id. Composite foreign keys — (org_id, account_id) pointing at accounts (org_id, id) — make a row that references another tenant’s data physically unstorable, which a plain single-column foreign key cannot express. Row-level security policies sit behind both, keyed to a transaction-local organization setting.

On top of that, access is role-scoped at the point where a tool is dispatched:

• viewer — reports and reads only. A viewer token cannot write to the ledger even if the model asks it to.
• bookkeeper — the full accounting surface: invoices, bills, payments, reconciliation, journal entries.
• admin — everything above, plus company settings.

And every mutation writes to an audit log with a timestamp and the actor. Voiding does not delete: it posts a reversing entry, so the history of what you believed and when stays intact. That is the part your accountant will care about in eleven months.

Two ways to connect

The hosted server speaks Streamable HTTP with OAuth 2.1 — authorization code with PKCE, dynamic client registration, refresh-token rotation. You add it once in Claude as a custom connector, sign in, pick your organization, and it is available on web, desktop and mobile.

Developers can instead run the stdio server locally against their own database, authenticating with an API key. Same tools, same rules, no network hop.

{
  "mcpServers": {
    "cosbooks": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "SUPABASE_DB_URL": "postgresql://...",
        "COSBOOKS_API_KEY": "cb_live_..."
      }
    }
  }
}

What this is not

CosBooks does not file your taxes, does not replace a CPA reviewing your year-end, and does not pretend that categorization is a solved problem. What it does is remove the data-entry layer between your business and a set of books that balance — and make the books queryable in the same sentence you would use to ask a bookkeeper.

If that sounds useful, the next post walks through setting it up end to end — it takes about ten minutes.