Ledger17 on Ledger17 | Headless Ledger

The MCP server

Fri, 14 Aug 2026 00:00:00 +0000

Endpoint


Endpoint	`https://mcp.ledger17.com/mcp`
Transport	Streamable HTTP
Authorization server	`https://auth2.sirktek.com`

Authorization

The server is an OAuth2 protected resource — it issues nothing and stores nothing. Every request must carry a bearer JWT, which the server validates (issuer, signature, expiry, audience) before any tool runs. The token is then forwarded verbatim to the command and query APIs together with the resolved tenant as X-Tenant-ID.

Permissions are enforced upstream, exactly as for direct API calls: reads require {orgId}:read:ledger, writes require {orgId}:write:ledger — see Authentication. A 403 from the APIs is surfaced to the model unchanged. The MCP server adds no permission logic of its own.

Balances

Thu, 23 Jul 2026 00:00:00 +0000

Single account balance

 GET /ledger/v1/balances

 curl "http://localhost:8081/ledger/v1/balances?accountReference=1500-receivables&timePeriodType=MONTHLY&timePeriodValue=2026-07&dimensionFilters=CUSTOMER:cust-001" \
 -H "X-Tenant-ID: org-84120557"

Query parameters

Parameter	Required	Notes
`accountReference`	yes	Must match `NNNN-slug`, e.g. `1500-receivables`
`timePeriodType`	yes	`YEAR`, `TERTIAL`, `QUARTER`, `BI_MONTHLY`, `MONTHLY`
`timePeriodValue`	yes	e.g. `2026-07`, `2026-Q1`, `2026`
`dimensionFilters`	no	A `TYPE:value` filter — one dimension type per query

Response — `200 OK`

 {
 "tenantId": "org-84120557",
 "accountReference": "1500-receivables",
 "timePeriod": "2026-07",
 "dimensionFiltersApplied": { "CUSTOMER": "cust-001" },
 "balanceMinorUnits": 125000,
 "currencyUnit": "EUR",
 "transactionCount": 3,
 "queryTimestamp": "2026-07-23T10:00:00.000Z",
 "cacheHit": true
}

balanceMinorUnits is signed and debit-positive: Σ debits − Σ credits.

Core concepts

Thu, 23 Jul 2026 00:00:00 +0000

Transaction blocks and entries

The unit of writing in Ledger17 is the transaction block: a named set of two or more accounting entries that must balance.

Each entry has:

Field	Meaning
`accountReference`	The account the entry posts to, e.g. `1920-bank`
`entryType`	`DEBIT` or `CREDIT`
`amountMinorUnits`	A signed integer amount at the unit’s scale — see Amounts and units
`dimensions`	Optional analytical tags, e.g. `{"CUSTOMER": "cust-001"}`
`lineDescription`	Optional free-text line description
`quantity`	Optional decimal quantity (e.g. number of shares)

A block is accepted only when the sum of its debit amounts equals the sum of its credit amounts. The accounting side of an entry is expressed through entryType, not through the sign of the amount.

Record transactions

Thu, 23 Jul 2026 00:00:00 +0000

Record a transaction batch

 POST /ledger/v1/transactions

The request body is an array of 1–1000 transaction commands. Even a single transaction is sent as a one-element array.

Headers

Header	Required	Notes
`X-Tenant-ID`	yes	Tenant the transactions belong to
`X-Idempotency-Key`	yes	Missing key → `400 VALIDATION_ERROR`
`X-Correlation-ID`	no	Optional UUID

Request body

 [{
 "name": "Sales invoice #42",
 "description": "July invoice for cust-001",
 "documentReference": "INV-2026-0042",
 "transactionDate": "2026-07-01",
 "unit": "EUR",
 "entries": [
 { "accountReference": "1500-receivables", "entryType": "DEBIT", "amountMinorUnits": 125000,
 "lineDescription": "Invoice total incl. VAT",
 "dimensions": { "CUSTOMER": "cust-001" } },
 { "accountReference": "3000-sales", "entryType": "CREDIT", "amountMinorUnits": 100000 },
 { "accountReference": "2700-vat-out", "entryType": "CREDIT", "amountMinorUnits": 25000 }
 ],
 "dimensions": [
 { "dimensionType": "PROJECT", "valueReference": "0b9f3c1e-…" }
 ],
 "applicationMetadata": { "source": "billing-service" }
}]

Field	Type	Constraints
`name`	string	required, ≤ 200 chars
`description`	string	≤ 2000 chars
`documentReference`	string	≤ 100 chars
`transactionDate`	date	required, `yyyy-MM-dd`
`unit`	string	required, ≤ 20 chars — a currency (`EUR`, `JPY`, …) or other registered unit (`kgCO2e`, `hours`, …)
`entries`	array	required, minimum 2 entries
`entries[].accountReference`	string	required, ≤ 50 chars
`entries[].amountMinorUnits`	integer	required; signed, scaled by the unit (Amounts and units) — negative means “reduce this side”
`entries[].entryType`	enum	required, `DEBIT` or `CREDIT`
`entries[].lineDescription`	string	≤ 500 chars
`entries[].dimensions`	object	map of dimension type → value
`entries[].quantity`	decimal	optional, ≥ 0 (e.g. shares)
`dimensions`	array	block-level `{dimensionType, valueReference}`
`applicationMetadata`	object	free-form
`enforceCapture`	boolean	optional; enforce dimension-capture validation

Every block must balance: the signed sum of DEBIT amounts must equal the signed sum of CREDIT amounts. See Negative amounts for what a negative entry means.

Connect a client

Fri, 14 Aug 2026 00:00:00 +0000

Choose the right credential

Situation	Credential	Tenant
You are talking to the assistant yourself	Your own Ledger17 login	Chosen in conversation if you belong to several
An agent runs unattended, without you	An API key	Bound to one tenant, never chosen

If in doubt: when a person is driving the assistant, the assistant should use that person’s login.

Claude.ai

Go to Settings → Connectors → Add custom connector.
Paste the endpoint: https://mcp.ledger17.com/mcp
Complete the login in the window that opens.

The client discovers the authorization server itself from the protected-resource metadata — nothing else to configure.

Authentication

Thu, 23 Jul 2026 00:00:00 +0000

Bearer tokens

In production both services require an OIDC JWT bearer token on every request — there are no anonymous endpoints:

 curl https://api.example.com/ledger/v1/balances?… \
 -H "Authorization: Bearer <JWT>" \
 -H "X-Tenant-ID: org-84120557"

In local development (dev/test profiles) OIDC is disabled and the tenant falls back to a configured development tenant — you can call the API without a token.

Tenant scoping

Send the organization id in the X-Tenant-ID header on every request. If the header is missing or blank, the API responds 400. The token must grant access to that same organization, otherwise the API responds 403.

Business events

Thu, 23 Jul 2026 00:00:00 +0000

Submit a business event

 POST /ledger/v1/events

The event is validated against the applicable rule sets’ ontologies, entries are derived, conflicts between rule sets are detected — and only then is the event appended. Processing is asynchronous: the API answers 202 Accepted.

Headers

Header	Required
`X-Tenant-ID`	yes
`Authorization`	in production

Request body

 {
 "eventType": "SalesInvoice",
 "transactionDate": "2026-07-01",
 "accountingEntries": [
 { "accountCode": "1500-receivables", "entryType": "DEBIT", "amount": 125000,
 "currency": "EUR", "description": "Invoice #42",
 "dimensions": { "CUSTOMER": "cust-001" } },
 { "accountCode": "3000-sales", "entryType": "CREDIT", "amount": 100000, "currency": "EUR" },
 { "accountCode": "2700-vat-out", "entryType": "CREDIT", "amount": 25000, "currency": "EUR" }
 ],
 "metadata": {
 "idempotencyKey": "f4b6a2d8-1c3e-4f5a-9b7d-8e2f0a1c3b5d",
 "tags": { "channel": "webshop" }
 }
}

Field	Type	Constraints
`eventType`	string	required, e.g. `SalesInvoice`, `PayrollRun`
`transactionDate`	date	optional `yyyy-MM-dd`; defaults to today
`accountingEntries`	array	required, non-empty
`accountingEntries[].accountCode`	string	required
`accountingEntries[].entryType`	enum	required, `DEBIT` or `CREDIT`
`accountingEntries[].amount`	integer	scaled by the unit — see Amounts and units
`accountingEntries[].currency`	string	optional — a currency or other registered unit
`accountingEntries[].dimensions`	object	optional
`metadata.idempotencyKey`	string	optional; parsed as a correlation UUID when valid
`metadata.tags`	object	optional string map

Response — `202 Accepted`

 { "eventId": "9c2e4f6a-…", "message": "Event accepted for processing" }

Errors

Status	Code	Cause
`400`	`VALIDATION_ERROR`	Bad `entryType`, missing fields
`400`	—	Ontology violations: `{"error": "Event validation failed against ontology constraints", "violations": [...]}`
`403`	`FORBIDDEN`	No write access to tenant
`409`	—	Conflicting rule-set derivations (body lists `conflictingEntries` per domain)

Inquire events

 GET /ledger/v1/events

A lightweight read on the command side, useful for reconciliation and for finding events that still lack a correction.

Transaction lines

Thu, 23 Jul 2026 00:00:00 +0000

List transaction lines

 GET /ledger/v1/transactions

 curl "http://localhost:8081/ledger/v1/transactions?from=2026-07-01&to=2026-07-31&account=1500-receivables&dimension=CUSTOMER:cust-001" \
 -H "X-Tenant-ID: org-84120557"

Query parameters

Parameter	Required	Notes
`from`	yes	Accounting-date lower bound, `yyyy-MM-dd`
`to`	no	Upper bound; defaults to `from`
`account`	no	Exact account reference
`dimension`	no	One `TYPE:value` pair
`limit`	no	Default 1000, capped at 5000

Response — `200 OK`

One element per entry line:

 [
 {
 "transactionId": "7d9e1a4c-…",
 "transactionDate": "2026-07-01",
 "accountReference": "1500-receivables",
 "entryType": "DEBIT",
 "amountMinorUnits": 125000,
 "lineDescription": "Invoice total incl. VAT",
 "dimensions": { "CUSTOMER": "cust-001" },
 "quantity": null,
 "recordedAt": "2026-07-01T09:14:03.512Z"
 }
]

Status	Cause
`400`	Invalid date or dimension syntax
`403`	No read access to tenant

API keys

Fri, 14 Aug 2026 00:00:00 +0000

When you need one

Only when something works with the ledger without a signed-in user:

another system integrating against the Ledger17 APIs — an invoicing system posting sales, a payroll run posting salaries, a bank feed posting settlements
an AI agent running unattended, with nobody present to approve a login

When a person uses Ledger17 — or an assistant works on behalf of a signed-in person — no API key is involved: the person’s own login is the credential.

Batch import

Thu, 23 Jul 2026 00:00:00 +0000

Submit a batch

 POST /ledger/v1/events/batch

Headers

Header	Required
`X-Tenant-ID`	yes

Request body

events holds 1–10 000 items:

 {
 "events": [
 {
 "eventType": "SalesInvoice",
 "date": "2026-01-31",
 "documentReference": "INV-2026-0001",
 "description": "January invoice",
 "accountingEntries": [
 { "accountCode": "1500-receivables", "entryType": "DEBIT", "amount": 125000, "currency": "EUR" },
 { "accountCode": "3000-sales", "entryType": "CREDIT", "amount": 100000, "currency": "EUR" },
 { "accountCode": "2700-vat-out", "entryType": "CREDIT", "amount": 25000, "currency": "EUR" }
 ]
 }
 ]
}

Field	Type	Constraints
`events`	array	required, 1–10 000 items
`events[].eventType`	string	required
`events[].date`	date	required, `yyyy-MM-dd`
`events[].documentReference`	string	≤ 255 chars; unique per tenant
`events[].description`	string	optional
`events[].accountingEntries`	array	required, non-empty; same shape as business events
`events[].metadata`	object	optional

Responses

The response always reports how many items were accepted and lists per-item errors:

Errors & status codes

Thu, 23 Jul 2026 00:00:00 +0000

The error envelope

Errors are returned as JSON with a stable shape. violations and timestamp are omitted when empty:

 {
 "error": "VALIDATION_ERROR",
 "message": "Transaction block must balance",
 "violations": ["entries: sum of debits (125000) != sum of credits (100000)"],
 "timestamp": "2026-07-01T09:14:03.512Z"
}

Two write-path errors use specialized shapes:

Batch size exceeded (413):

 {
 "error": "BATCH_SIZE_EXCEEDED",
 "message": "Batch size 1500 exceeds maximum allowed size of 1000",
 "maxBatchSize": 1000,
 "requestedSize": 1500
}

Idempotency / conflict responses on event submission (409) include the conflicting entries per domain:

Subledger rollups

Thu, 23 Jul 2026 00:00:00 +0000

Subledger rollup

 GET /ledger/v1/subledger

Rolls an account range up per dimension value — e.g. receivables per CUSTOMER. Rollups are served from views that are pre-aggregated for every dimension type as transactions post, so the query is a lookup regardless of ledger size; each request filters on one dimension type:

 curl "http://localhost:8081/ledger/v1/subledger?accounts=1500&dimensionType=CUSTOMER&timePeriodType=YEAR&timePeriodValue=2026" \
 -H "X-Tenant-ID: org-84120557"

Query parameters

Parameter	Required	Notes
`accounts`	yes	4-digit codes and/or ranges, comma-separated: `1500` or `5000-5999`
`dimensionType`	yes	`CUSTOMER`, `SUPPLIER`, `EMPLOYEE`, `COUNTERPARTY`, `ASSET`
`timePeriodType`	yes	`YEAR`, `TERTIAL`, `QUARTER`, `BI_MONTHLY`, `MONTHLY`
`timePeriodValue`	yes	e.g. `2026`

Response — `200 OK`

Debit-positive minor units. A dimensionValue: null row collects entries in the range that carry no tag of the requested type:

Party exposure

Thu, 23 Jul 2026 00:00:00 +0000

Get a party’s exposure

 GET /ledger/v1/parties/{partyId}/exposure

partyId is the party’s UUID. The same party may appear as customer, supplier and owner — the endpoint sums each role separately and nets AR against AP.

 curl "http://localhost:8081/ledger/v1/parties/6f1c…/exposure?receivableAccounts=1500&payableAccounts=2400&timePeriodType=YEAR&timePeriodValue=2026" \
 -H "X-Tenant-ID: org-84120557"

Query parameters

Parameter	Required	Notes
`receivableAccounts`	yes	Codes/ranges for accounts receivable
`payableAccounts`	yes	Codes/ranges for accounts payable
`ownerAccounts`	no	Codes/ranges for owner/equity accounts
`timePeriodType`	no	Default `YEAR`
`timePeriodValue`	no	Default: current year

Response — `200 OK`

 {
 "partyId": "6f1c…",
 "timePeriodType": "YEAR",
 "timePeriodValue": "2026",
 "receivable": 50000,
 "payable": 20000,
 "net": 30000,
 "roles": [
 { "role": "CUSTOMER", "accountCodes": ["1500"], "balance": 50000 },
 { "role": "SUPPLIER", "accountCodes": ["2400"], "balance": -20000 }
 ]
}

net = receivable − payable. An owner/COUNTERPARTY balance appears in roles but is excluded from net.

Dead-letter queue

Thu, 23 Jul 2026 00:00:00 +0000

The dead-letter queue is an operations surface: listing can span tenants, but everything requires the {orgId}:admin:ledger permission — the list only shows tenants you hold admin:ledger for, and reading, reprocessing or discarding a record requires admin:ledger on that record’s tenant. Operations against another tenant’s records answer 403 FORBIDDEN.

List failed events

 GET /ledger/v1/failed-events

Parameter	Notes
`tenantId`	Filter by tenant (requires read access to it)
`eventType`	Filter by event type
`reprocessed`	`true`/`false` — filter by reprocessing state

200 response:

Journal & event stream

Thu, 23 Jul 2026 00:00:00 +0000

Paginated journal

 GET /ledger/v1/journal

Newest-first pages of posted transaction events. Use it to load history before subscribing to the live stream.

Parameter	Required	Notes
`limit`	no	Default 50, hard cap 200
`before`	no	Global-sequence cursor; returns older events. Omit for the latest page

Response — `200 OK`

 {
 "events": [ { "…": "TransactionEventDto — see below" } ],
 "maxGlobalSeq": 1042
}

Pass maxGlobalSeq as the WebSocket fromSequence to continue seamlessly from where the history ends.

Ledger17 on Ledger17 | Headless Ledger

The MCP server

Endpoint link

Authorization link

Balances

Single account balance link

Query parameters link

Response — 200 OK link

Core concepts

Transaction blocks and entries link

Record transactions

Record a transaction batch link

Headers link

Request body link

Connect a client

Choose the right credential link

Claude.ai link

Authentication

Bearer tokens link

Tenant scoping link

Business events

Submit a business event link

Headers link

Request body link

Response — 202 Accepted link

Errors link

Inquire events link

Transaction lines

List transaction lines link

Query parameters link

Response — 200 OK link

API keys

When you need one link

Batch import

Submit a batch link

Headers link

Request body link

Responses link

Errors & status codes

The error envelope link

Subledger rollups

Subledger rollup link

Query parameters link

Response — 200 OK link

Party exposure

Get a party’s exposure link

Query parameters link

Response — 200 OK link

Dead-letter queue

List failed events link

Journal & event stream

Paginated journal link

Response — 200 OK link

Endpoint

Authorization

Single account balance

Query parameters

Response — `200 OK`

Transaction blocks and entries

Record a transaction batch

Headers

Request body

Choose the right credential

Claude.ai

Bearer tokens

Tenant scoping

Submit a business event

Headers

Request body

Response — `202 Accepted`

Errors

Inquire events

List transaction lines

Query parameters

Response — `200 OK`

When you need one

Submit a batch

Headers

Request body

Responses

The error envelope

Subledger rollup

Query parameters

Response — `200 OK`

Get a party’s exposure

Query parameters

Response — `200 OK`

List failed events

Paginated journal

Response — `200 OK`