Setup & Basics

LedgerLou exposes an MCP server over Streamable HTTP. Every app with MCP support — Claude, Mistral, ChatGPT — connects through the same endpoint and the same OAuth flow.

Fastest entry point

Let the agent lead

Once the MCP server is connected, you do not need to read through the integration yourself. Just tell your LLM (Claude, ChatGPT, Mistral, …) directly:

Let's tackle the bookkeeping in my LedgerLou ledger.

The agent will then call the relevant tools on its own, discover the right Skill playbook for the job via prompts/list, and build the workflow for your business — without requiring you to know every tool signature up front.

Endpoint

MCP Server https://api.ledgerlou.de/mcp

Authentication

OAuth 2.0 PKCE

Recommended for interactive clients

Clients register automatically via RFC 7591. The authorization server is discovered through /.well-known/oauth-protected-resource — no client secret required. After connecting, you are redirected to the LedgerLou sign-in page, where you log in and grant the scopes you want.

API key

For your own agents & backends

Send the API key directly as a bearer token: Authorization: Bearer ll_<your-key>. Keys are created in the Dashboard under Settings → API keys and carry exactly the scopes assigned at creation time.

Technical reference

Parameter	Value
Transport	Streamable HTTP (MCP specification 2025-03-26)
Endpoint	`https://api.ledgerlou.de/mcp`
Auth	OAuth 2.0 PKCE (S256) — no client secret required
Dynamic registration	RFC 7591 — clients register automatically
Alternative	API key as `Authorization: Bearer ll_…`
Protected Resource Metadata	`https://api.ledgerlou.de/.well-known/oauth-protected-resource`
Authorization Server Metadata	`https://api.ledgerlou.de/.well-known/oauth-authorization-server`

Quick Connect

Copy the matching config snippet into your app's MCP configuration. Replace ll_your-api-key with your API key from the dashboard.

Claude Code / Cursor / Windsurf

~/.claude/mcp.json / .cursor/mcp.json

Clients with native HTTP transport — configure directly with url and headers.

{
  "mcpServers": {
    "ledgerlou": {
      "type": "url",
      "url": "https://api.ledgerlou.de/mcp",
      "headers": {
        "Authorization": "Bearer ll_dein-api-key"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json

Claude Desktop only supports stdio-based servers. mcp-remote serves as a bridge to the HTTP endpoint.

{
  "mcpServers": {
    "ledgerlou": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.ledgerlou.de/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ll_dein-api-key"
      }
    }
  }
}

Prerequisite

Node.js must be installed — npx downloads mcp-remote automatically. If the connection fails after a crash (EADDRINUSE), kill the orphan process: lsof -i :19103 → kill <PID>.

OAuth instead of an API key?

Claude Desktop, ChatGPT, and other MCP hosts with OAuth support connect automatically via the PKCE flow — no manual config required. Just add https://api.ledgerlou.de/mcp as an MCP server and the app will redirect you to the sign-in page.

Scopes

Scopes determine which modules and actions a connected app can access. Format: module:action — for example journal:read, bank:write. A full overview is available under Auth & Scopes.

Changing scopes

Scopes can only be changed after the fact by disconnecting and reconnecting: revoke the connection in the dashboard under Connected Apps, reconnect the app, and select the desired scopes during the OAuth flow.

Skills (built-in playbooks)

Beyond the 71 tools, the MCP server ships task-scoped playbooks as MCP prompts (prompts/list, prompts/get). Each skill is a procedural guide for one end-to-end workflow — the agent discovers the relevant one for the job it was asked to do and follows it step by step. Markdown is bilingual: DE-locale tenants get the German version automatically; EN is the default elsewhere.

Skill	Covers	Required scopes
`process_incoming_invoice`	Accounts-payable booking of unpaid incoming invoices: inbox triage, vendor creation, expense account + tax-scenario selection, booking (Aufwand → Kreditoren), and invoice record (manual AP flow and atomic `approve_invoice_review_case` path).	`payables:`, `journal:`
`process_outgoing_invoice`	Accounts-receivable end-to-end: customer creation, revenue classification, tax scenario confirmation, credit-note path, and customer-payment reconciliation.	`receivables:`, `journal:`, `bank:*`
`reconcile_bank_transactions`	Bank reconciliation: `candidate_kind` selection, batch matching, split groups, and unmatch/dismiss recovery.	`bank:read`, `bank:write`
`tenant_setup_migration`	Tenant bootstrap & migration wizard: chart of accounts, tax codes, bank accounts, opening balances, pre-migration transaction flagging. Admin-only — invisible to OAuth clients because it needs `config:write`.	`admin`

Skill resources alongside prompts

The same markdown is also served as MCP resources for clients that do not surface prompts/*: ledgerlou://skills/<slug> (EN) and ledgerlou://skills/<slug>/de (DE). Public fetch: https://docs.ledgerlou.de/skills/<slug>.md.

Architecture

AI app

e.g. Claude, Mistral, ChatGPT

→

MCP client

Built into the AI host

→

LedgerLou MCP

api.ledgerlou.de/mcp

→

General ledger

GoBD-compliant, append-only

Typical agent flow

Token & scopes

The agent receives an OAuth token or API key with the minimum scopes needed for its task.

Discover the playbook

The agent calls prompts/list, picks the matching skill (e.g. process_incoming_invoice), loads it via prompts/get, and follows its steps.

Load context

The agent loads live context through read tools: chart of accounts, open periods, bank status — always from the live general ledger, never from training data.

Form a proposal

The agent builds a proposal (journal entry, match, review decision) based on the loaded data.

Get approval

Write actions require an explicit approval — either from the user in chat or via the LedgerLou dashboard.

Write & confirm

The tool writes to the ledger and returns an intent_id, booking ID, or status — fully traceable.

Approval model — what the server enforces and what it does not

Server-enforced

What the server enforces

Parameter validation — accounts must exist, debit must equal credit
Scope checks — no post_booking without journal:write
Duplicate detection — SHA256 hash prevents double postings
Rate limiting — max. 60 requests/minute per tenant
Hard lock — period locks are only set through the dashboard/REST, not via MCP

Not enforced

What the server does not enforce

There is no server-side approval gate before write tools. The MCP server sends agent instructions that tell the LLM to show a summary before every write action and wait for confirmation.

These instructions are a behavioral contract with the LLM — not a technical enforcement. An API key with write scopes can call write tools directly, without anyone having approved.

User responsibility

LedgerLou provides the infrastructure — the general ledger, the tools, the scopes, the audit trails. How agents are configured, which scopes they receive, and which controls gate productive write actions is the user's responsibility.

In particular this includes:

Scope management — every agent receives only the rights its use case actually needs (principle of least privilege).
Agent configuration — system prompts, approval logic, and review steps are defined and maintained by the user.
Internal control system (ICS) — four-eyes principle, spot checks, and periodic reviews are the user's responsibility to set up.

Infrastructure vs. bookkeeping

LedgerLou is not a tax-advisory service or a bookkeeping service. We provide the technical infrastructure — GoBD-compliant, append-only, scope-controlled, tenant-isolated. The user builds their bookkeeping on top of it and is responsible for its professional and legal correctness.