Developers — Ledgerbook Docs, Quickstart & MCP

Self-host install

One process on a VM or a bare-metal HA cluster; containers optional. An offline bundle with zero egress for air-gapped sites, designed to install without a control-plane callback.

NFR-6 · PH-1

MCP client connect

Remote or stdio; the read and propose surface ships at PH-1 with the same semantics and error taxonomy as HTTP — including air-gapped, with your own local model.

FR-343 · PH-1 read/propose; full tool surface Roadmap

Agent credentials

Bootstrap programmatically: scoped, short-lived credentials with a test class that can never write to a production ledger, and per-credential usage you can audit.

FR-807 · PH-1

Phase legend: PH-1 shipped now · Roadmap arrives with PH-2. Labels are always present — colour is never the only signal.

Quickstart: validate, then draft

Nothing is written before validation. The validator runs balance, currency, account-state, dimension and equation checks and returns structured errors — the same pre-commit surface agents call.

REST · validate before commitPH-1

# 1 · dry-run — the validator writes nothing
POST /v1/validate
{
  "ledger": "grp-eu", "book": "group_ifrs",
  "entry": { "date": "2026-09-19", "postings": [
      { "account": "1000", "side": "debit",  "amount_minor": 125000, "currency": "EUR" },
      { "account": "4000", "side": "credit", "amount_minor": 125000, "currency": "EUR" } ] }
}

← 200 { "valid": true, "equation_ok": true, "errors": [] }
# 2 · draft it: POST /v1/provisions   ·   3 · approve and finalize when policy allows

The surfaces you call

Two REST endpoints and the MCP tools that mirror them — the same API semantics on both surfaces. Every write path accepts an idempotency key; money-bearing keys never expire. Verification is first-class: check immutability online or offline, and replay a signed export into a fresh deployment (FR-121/813).

POST /v1/validate

Dry-run the full validator — balance, currency, account state, dimensions, equation and policy — and get structured, machine-readable errors without writing anything.

FR-116/149 · PH-1

POST /v1/provisions

Draft-first: create, revise and submit a Provisional entry. Direct posting is refused when the policy requires draft approval — the gate lives server-side, not in the client.

FR-201/206 · PH-1

read get_balance

As-of and as-believed balances by ledger, book, scenario and account — returned with the chain position of the events that produced them.

propose create_provision

Propose an entry over MCP. Proposals run the materiality gate; agents hold no posting rights of their own, and every call appends a provenance event.

Machine surfaces

The site and the ledger are both readable by machines first — that is the product, not a gesture.

llms.txt — curated index for agent-mediated discovery
sitemap.xml — canonical, indexable URLs only
security.txt — vulnerability disclosure contact
OpenAPI, GraphQL SDL and the MCP tool manifest ship with the developer preview, generated from one source of truth (FR-343, OI-20)

Docs map

The docs site ships with the developer preview under /docs — same host, no subdomain split.

Quickstart — first entry in under 10 minutes
Concepts — entries, postings, the lifecycle, as-of reads
Reference — REST, CLI, streaming and MCP generated from OpenAPI
Interfaces — MCP quickstart, agent credentials, webhooks
Ops — deployment, offline bundle, backup and chain verification in CI

Roadmap (PH-2) docs — compliance packs, statutory exports, PQC migration — are labelled in the docs themselves.

Developer FAQ

Is there a hosted sandbox I can try?

No hosted sandbox ships at PH-1. The quickstart runs locally: a single process, a local data directory, no egress required. That is deliberate — the deployment you test is the shape you deploy.

Where is the API reference?

The reference publishes with the developer preview at /docs, generated from the OpenAPI spec and the MCP tool manifest so the two cannot drift. Until then, llms.txt indexes what exists.

How do I connect an agent today?

Over MCP, the read/propose surface. The agent authenticates with a scoped credential, reads balances and entries, and proposes changes that run the materiality gate server-side. Direct agent posting without an approval path is refused by design; the full tool surface is on the roadmap.

Build with the ledger

The builder preview opens to design partners first; the docs quickstart is the front door.

Join the builder preview See the MCP surface

Post your first entry in under 10 minutes