Footnote

Footnote

An MCP server that prevents hallucinated numbers when AI answers questions over ERP and finance data. Every figure in an answer traces back to the database rows that produced it: clickable at read time, exportable for an auditor, and tamper-evident.

Works with any MCP client: Claude Desktop, Cursor, Microsoft Agent Framework, Semantic Kernel (.NET), LangChain, or your own loop.

An MCP server, a provenance store, and a demo UI showing what the combination looks like.

The quickest way to try it:

// claude_desktop_config.json — sample data, nothing to install

{ "mcpServers": { "footnote": { "command": "npx", "args": ["-y", "@brick-byte/footnote"], "env": { "PROVENANCE_ACTOR": "your-name" } } } }

Against your own database it reads from two, never one — the ERP read-only, the audit trail somewhere you own. Run footnote check first; see Connecting to an existing database.

{ "mcpServers": {

"footnote": { "command": "npx", "args": ["-y", "@brick-byte/footnote"], "env": { // Read-only role. Footnote never writes here and never migrates it. "DATABASE_URL": "postgres://footnote_ro:pass@host:5432/erp", // The append-only provenance log, deliberately a separate database. "PROVENANCE_DB": "/path/to/footnote-provenance.db", "PROVENANCE_ACTOR": "your-name" } } } }

Or run the demo UI locally:

npm install

npm run demo # http://localhost:4711 npm test # 30 tests, including the invariants below

Node 22.5+ required (uses the built-in node:sqlite, so there is no database to install).

Postgres is opt-in. The same schema, seed and query set run against it, and the same suite has to pass on both:

npm run db:up     # Postgres 17 in Docker, seeded from migrations/001_init.sql

npm run test:pg # the same suite + 2 Postgres-only checks (32) npm run demo:pg # the demo, against Postgres

The problem

Language models produce plausible continuations, not true ones. Point one at a business database and it will confidently report a number that no query produced — and the fabricated figure is indistinguishable from the real one, because both come out of the same machinery.

The usual answers don't hold up here. Uncertainty signals catch the fuzzy cases, not the fluent ones. A verifier built from the same model can confirm a fabrication as easily as catch it. And in finance, inventory or procurement, "the model said so" is not an answer anyone can act on.

What does work is structural: never let the model produce the number.

The architecture

  question

│ ▼ model ──────────► picks an operation from a catalog and supplies typed args │ (it cannot write SQL, cannot invent an operation) ▼ contract layer ─► validates params, resolves entities against the database, │ rejects anything that does not exist ▼ deterministic ──► executes the query; SQL does all aggregation core returns values + the evidence behind each one │ ▼ provenance ─────► appends a hash-chained record, server-side, store where the model cannot influence it │ ▼ host UI ────────► fills slots from structured output and renders each claim as a clickable citation

The model handles translation and phrasing — the two things it is reliable at. Numbers come from the system of record.

What it enforces

These are tests, not guidelines. npm test fails if any of them breaks.

No number is generated. Values are copied verbatim from an operation's structured output into template slots. A test asserts every monetary figure in an answer is covered by a claim with evidence behind it, and that the stated total equals the sum of the records it cites.

Entities are validated before any query runs. A fabricated customer produces a recoverable error listing real alternatives — not a silent empty result the model narrates around.

Aggregation happens in SQL. The model chooses which aggregation to run, never what it equals.

Empty results are handled in code. This is the single biggest fabrication trigger: hand a model an empty result set mid-sentence and it invents something to finish the sentence. Operations set an explicit emptyReason instead.

Unroutable questions are refused. "What will revenue be next quarter?" maps to no operation, so no answer is produced. Refusal is a first-class outcome, not a failure.

Provenance is written server-side. The model never reports its own provenance. Provenance that depends on the model choosing to cite is worthless.

The log is tamper-evident. Each record carries the hash of its predecessor. npm run verify walks the chain and reports the first record that was modified after it was written.

Query ordering is a tested contract. listCustomers must return record order, because entity extraction takes the first match. Sorting it by name instead produces the failure this project exists to prevent: a fluent sentence, a real figure, correctly cited to real rows, about the wrong company. There is a test for exactly that.

Interpretations, not just figures

The harder case is judgement. "Bergmann is at risk" is a conclusion with no row to check it against — and an ungrounded interpretation is more dangerous than an ungrounded number, because it reads as insight and survives review.

The answer here states the conclusion and then lays out each premise as a separately cited fact:

Bergmann Logistik GmbH shows two independent risk signals.

This is an interpretation — the underlying facts are:

· 43.805,00 € overdue across 4 invoices, oldest 104 days past due · 2 open support tickets, 1 high severity · agreed payment terms of 30 days, account owned by Ana Kovač

The conclusion is the model's. Every fact above is a record you can open.

A human can disagree with the reasoning while trusting the inputs.

Provenance record format

{

"id": "…", "sequence": 1, "timestamp": "2026-08-14T09:12:04.000Z", "actor": { "id": "zoran", "role": "controller" }, "question": "How much does Bergmann owe?", "answer": "Bergmann Logistik GmbH is 43.805,00 € overdue across 4 invoices…",

// Each claim indexes a span of the answer and names its evidence. "claims": [ { "text": "43.805,00 €", "span": { "start": 25, "end": 36 }, "evidenceIds": ["invoice:8812", "invoice:8834", "invoice:8901", "invoice:8977"], "origin": "structured" // never "generated" for a value } ],

// The query, so the result is reproducible. "operations": [ { "name": "getOverdueInvoices", "arguments": { "customer": "Bergmann", "asOfDate": "2026-08-14" }, "query": { "sql": "SELECT …", "params": ["2026-08-14", 4471, "2026-08-14"] }, "durationMs": 0.42 } ],

// Field values, not just IDs — the export stands alone if the source moves on. "evidence": [ { "id": "invoice:8812", "type": "invoice", "recordId": "8812", "uri": "erp://invoice/8812", "fields": { "number": "INV-2026-8812", "due_on": "2026-05-02", "outstanding": "18.450,00 €", "days_overdue": 104 } } ],

"previousHash": "0000…", "hash": "9aa2ba…" }

origin is the field that matters. structured means the value was copied from an operation's output. generated means a model produced it — which for a number is exactly what this project exists to prevent.

MCP details

The server uses the parts of the protocol that carry this work:

What MCP does not give you, and what this repo adds: nothing in the protocol binds *this claim* to *that evidence*. The protocol hands you links; the claim-to-evidence mapping and its rendering live in the host. That binding is the actual product.

Run standalone over stdio:

npm run mcp

The claude_desktop_config.json entry is at the top of this README.

Running from source (for development)

{ "mcpServers": {

"footnote": { "command": "npx", "args": ["tsx", "--experimental-sqlite", "/path/to/footnote/src/mcp-server.ts"], "env": { "PROVENANCE_DB": "/path/to/provenance.db", "PROVENANCE_ACTOR": "your-name" } } } }

Connecting to an existing database

By default Footnote runs against its own throwaway sample database. Set DATABASE_URL and it switches to external mode, meant for a database it did not create — a customer's ERP.

External mode changes three things, all of them about not damaging a system that isn't ours:

• The migration never runs. In demo mode Footnote creates and seeds customers, invoices, payments and tickets. Against a real database that would either crash on a read-only role or, worse, succeed — inserting fabricated invoices into a live finance system. FOOTNOTE_SEED=1 is the only way to opt back in, and exists for our own Docker Postgres.
• The ERP connection is read-only at the session level. Every pool connection starts with default_transaction_read_only=on and a statement_timeout. The catalog only ever emits SELECT, but that is a property of code someone can change; this is enforced by the server.
• The provenance log goes somewhere else. It is append-only and needs write access, so it never shares the ERP connection. Writing an audit trail into the database being audited would mean asking for write access to the very system under audit.

Create a read-only role

CREATE ROLE footnote_ro LOGIN PASSWORD '…';

GRANT CONNECT ON DATABASE your_erp TO footnote_ro; GRANT USAGE ON SCHEMA public TO footnote_ro; GRANT SELECT ON ALL TABLES IN SCHEMA public TO footnote_ro;

-- Postgres 15+ already revokes this from PUBLIC; older versions do not. REVOKE CREATE ON SCHEMA public FROM footnote_ro, PUBLIC;

-- So tables added later are readable too, without re-granting by hand. ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO footnote_ro;

Environment variables

Check before you connect

DATABASE_URL=postgres://footnote_ro:…@host:5432/erp npm run check

or, from the installed package, footnote check. It reports t