Build

MCP server

Run ledgerforge-mcp locally, enable write tools deliberately and bind it to an API key.

Full guide in the repository: docs/mcp.md

ledgerforge-mcp exposes a configured LedgerForge deployment as a local Model Context Protocol server over standard input and output. It uses the same configuration and database connection as the main service. It ships in the release archives and the container image, or you can build it with go install github.com/devaccuracy/ledgerforge/cmd/ledgerforge-mcp@v1.0.0.

Run it bound to a key

Terminal

# Inject the agent's scoped key through the MCP client's secret environment.$ export LEDGERFORGE_MCP_API_KEY='<agent key>'$ ledgerforge-mcp --config ./ledgerforge.json --allow-write

--api-keysupplies the same identity explicitly; the environment variable keeps the key off the command line. Each tool call resolves the key's current validity and scopes and applies its effective spending policy. Without a key, the process has deployment-level datasource authority and no policy identity, so always bind a key for an agent that must be constrained.

MCP client configuration (TOML)

[mcp_servers.ledgerforge]command = "/absolute/path/to/ledgerforge-mcp"args = ["--config", "/absolute/path/to/ledgerforge.json"]

There is no HTTP endpoint. Run it as a local subprocess, or behind a separately authenticated transport. Never expose its stdio stream through an unauthenticated proxy. Standard output is reserved for protocol messages; logs and audit events go to standard error.

Read and write tools

By default the server is read-only: it can retrieve and list ledgers, balances, transactions, historical balance states and fund lineage, with pagination capped at 100 records. Every balance and transaction result includes exact *_minor integer strings; use those, not floating-point amounts, for decisions.

Need	Capability
Find an account or wallet	`ledgerforge_find_balance`
Investigate a payment	`ledgerforge_get_transaction_context`
Audit a past position	`ledgerforge_get_balance_at_time`
Inspect the bound key's policy	`ledgerforge_effective_policy, ledgerforge_remaining_capacity, ledgerforge_pending_approvals`
Submit under the key's policy (writes on)	`ledgerforge_submit_policy_transaction`

--allow-write adds tools to create ledgers and balances, transfer funds, run controlled bulk batches, refund eligible transactions and commit or void holds. Each write produces a structured audit log entry and requires confirm: true. For ordinary transfers use ledgerforge_transfer_funds:

ledgerforge_transfer_funds arguments

{  "source_balance_id": "bal_customer_cash",  "destination_balance_id": "bal_merchant_payable",  "amount_minor": "1234",  "currency": "USD",  "currency_multiplier": 100,  "reference": "payment-order-1042",  "description": "Order 1042",  "confirm": true}

Production guidance

Use a dedicated database credential with only the permissions the enabled tools need.
Keep writes off for analysis, support and reporting agents.
Treat --allow-write as production access and collect the standard-error audit log.
confirm: true is an intent check. Approval decisions use the HTTP review endpoints with a separate approver key; see agent safety.
Keep the LedgerForge workers running for queued and scheduled transactions.