API base
/api/v1
Versioned Ledger Layer REST contract for business APIs and MCP discovery and invocation.
Developers
Ledger Layer developer documentation for the full product workflow.
Start with the comparison guide if you are still evaluating the workflow story. Use this page when you are implementing or supporting the same governed close path through docs, setup guidance, and the MCP bridge.
Overview
Reference blocks before you integrate
Ledger Layer is split into a versioned REST API and an HTTP MCP bridge. The bridge is not a separate product surface; it exposes the same governed workflows teams use inside Ledger Layer.
MCP bridge
POST /mcp
Streamable HTTP endpoint exposed by the Ledger Layer MCP bridge on the configured bridge port.
Auth model
Bearer first
Bearer auth is required for protected requests. The bridge expects Authorization headers from the client.
Safety model
Role + scope + tenant
Mutating tools are policy-gated and can require confirmation, approval, and idempotency.
Product Workflows
How users use Ledger Layer today
Developers should understand the live Ledger Layer operating model before automating it. These are the user-facing product areas already present in the application.
Upload & Ingest
Users upload CSV, XLSX, PDF, DOCX, or text, review extraction confidence, then confirm only clean records.
Mirror tools: smart_ingest.extract, smart_ingest.confirm, ingest.csv.extract, ingest.xlsx.extract, ingest.confirm
Portfolio
Users inspect the lease register by entity, standard, currency, asset class, expiry, and status.
Mirror tools: portfolio.search, portfolio.summary, portfolio.analytics, lease.detail, lease.schedule
Journal Entries
Users review, approve, reverse, void, and export journal entries with proper finance controls.
Mirror tools: journal.search, journal.summary, journal.detail, journal.approve, journal.approve_batch, journal.reverse, journal.void, journal.export
Disclosures
Users refresh disclosure sections, review tie-out issues, and prepare reporting output for the selected standard.
Mirror tools: disclosures.get, fsimpact.get
Assumptions & Governance
Users maintain IBR, FX, entity settings, and policy positions without pushing critical controls into side files.
Mirror tools: fx_rates.upsert, ibr_rates.upsert, entity_settings.upsert, policy.coverage, policy.conflicts, policy.resolve, policy.bind, policy.rebase
Getting Started
Choose the right auth path first
Ledger Layer works best when integrations use dedicated INTEGRATION service tokens. Human session tokens are still useful for local admin bootstrap and short-lived testing.
Recommended: service token
Use an INTEGRATION service token with mcp:tools:list, mcp:invoke, the required domain scopes, and a narrow allowed_tools list.
Bootstrap: human session token
For local development you can log in with an ADMIN or OWNER account and use the returned access token, but it is short-lived and less suitable for repeat use.
create-service-token.shbash
1curl -X POST "https://api.your-ledgerlayer-domain.com/api/v1/auth/service-tokens" \2 -H "Authorization: Bearer <admin_access_token>" \3 -H "Content-Type: application/json" \4 -H "Idempotency-Key: <uuid>" \5 -d '{6 "name":"aaos-mcp-bridge",7 "role":"INTEGRATION",8 "scopes":["mcp:tools:list","mcp:invoke","portfolio:read","lease:read","journal:read","engine:run"],9 "allowed_tools":["system.metadata","system.health","portfolio.summary","lease.detail","journal.search","engine.run"],10 "display_name":"Ledger Layer MCP Bridge",11 "ttl_days":3012 }'start-mcp-bridge.shbash
1LEDGERLAYER_API_BASE_URL=https://api.your-ledgerlayer-domain.com \2MCP_BRIDGE_PORT=3333 \3node mcp/bridge-http.mjs- Start Ledger Layer and the MCP bridge. The bridge translates MCP tools/list and tools/call into Ledger Layer REST requests.
- Mint or obtain a bearer token with the right scopes before registering the MCP server.
- Always include the Authorization header when adding the bridge to Claude Code, Codex, or another HTTP MCP client.
- Verify connectivity with GET /healthz on the bridge and a simple system.health tool call.
MCP Setup
Connect Claude Code, Codex, or another HTTP MCP client
Ledger Layer MCP is header-based and streamable-HTTP based. Always send the Authorization header. If you omit it, some clients attempt OAuth discovery and fail before they ever reach tools/list.
Recommended CLI registration
Use the bridge URL directly and pass the bearer token in the header when registering the server in Claude Code or other compatible tools.
Project config option
For project-level configuration, keep the bridge in .mcp.json and source the bearer token from the environment.
claude-mcp-add.shbash
1claude mcp add --transport http \2 --header "Authorization: Bearer <service_token>" \3 aaos http://127.0.0.1:3333/mcp.mcp.jsonjson
1{2 "mcpServers": {3 "aaos": {4 "type": "http",5 "url": "http://127.0.0.1:3333/mcp",6 "headers": {7 "Authorization": "Bearer ${Ledger Layer_MCP_TOKEN}"8 }9 }10 }11}REST API
Use REST directly when you need the business API surface
MCP is the transport that AI tools use, but the underlying Ledger Layer business surface remains a standard versioned REST API with a uniform response envelope and strict auth rules.
list-tools.shbash
1curl -X GET "https://api.your-ledgerlayer-domain.com/api/v1/mcp/tools" \2 -H "Authorization: Bearer <token>"response-envelope.jsonjson
1{2 "ok": true,3 "data": { "...": "..." },4 "meta": { "request_id": "..." }5}Auth headers
Ledger Layer supports Authorization: Bearer <token> for user sessions and service tokens, and Authorization: ApiKey <key> for API-key based integrations.
Mutation safeguards
Business writes expect explicit confirmation for accounting actions, and MCP mutating tools can require idempotency, approval state, and runtime policy checks.
Tool Catalog
Tool families exposed by Ledger Layer MCP
The MCP manifest covers system metadata, lease operations, ingestion, engine runs, journals, disclosures, governance, and tenant-level admin writes.
System and prompts
system.metadata, system.health, prompt.template.get
Portfolio and leases
portfolio.search, portfolio.summary, portfolio.analytics, lease.detail, lease.schedule, lease.extract, lease.extract_file, lease.confirm
Ingest and engine
ingest.csv.extract, ingest.xlsx.extract, smart_ingest.extract, ingest.confirm, smart_ingest.confirm, engine.run, engine.monthly_close
Journals and reporting
journal.search, journal.summary, journal.detail, journal.approve, journal.approve_batch, journal.reverse, journal.void, journal.export, disclosures.get, fsimpact.get
Governance and admin writes
notifications.list, notifications.create, notifications.set_status, audit.list, policy.coverage, policy.conflicts, policy.grandfathering, policy.resolve, policy.bind, policy.rebase, entity_settings.upsert, fx_rates.upsert, ibr_rates.upsert
Common Workflows
Documented automation paths
These are the main flows teams usually automate once the bridge is connected and the service token has the right scopes.
Onboard lease source files
Classify and extract mixed artifacts with smart_ingest.extract, review the result, then write approved records with smart_ingest.confirm.
Run the accounting engine
Use engine.run for lease-level scenarios or engine.monthly_close for a date-based portfolio close with explicit confirm: true.
Control finance outputs
Search and approve journals, then export only approved entries to downstream systems or reviewers.
Generate reporting output
Call disclosures.get and fsimpact.get for standard-aware reporting artifacts tied to the same underlying records.
engine.monthly_close.shbash
1curl -X POST "https://api.your-ledgerlayer-domain.com/api/v1/mcp/tools/engine.monthly_close/invoke" \2 -H "Authorization: Bearer <token>" \3 -H "Content-Type: application/json" \4 -H "Idempotency-Key: <uuid>" \5 -d '{"confirm":true,"as_of_date":"2026-03-31","entity":"ACME Holdings LLC"}'Troubleshooting
Resolve the common failure modes quickly
Ledger Layer errors are usually one of four things: bridge not reachable, bearer header missing, scopes too narrow, or the login bootstrap path hitting MFA or token expiry.
Cannot POST /register
Some MCP clients attempt OAuth discovery when no Authorization header is configured. Ledger Layer bridge setup should always include the bearer header explicitly.
Authorization header missing
The bridge received a request without a bearer token. Confirm the MCP client is sending Authorization: Bearer <token> on every request.
MCP_FORBIDDEN_SCOPE
The principal is missing mcp:invoke, mcp:tools:list, or a tool-specific scope. Reissue the service token with least-privilege but sufficient scopes and allowed_tools.
MFA blocks login bootstrap
If a human login returns mfa_required, complete POST /api/v1/auth/mfa/verify first and then use the returned access token.
Bridge health check fails
Confirm Ledger Layer is running, the bridge is on the expected port, and GET /healthz returns a healthy JSON response before testing tools.
Need Help?
Use the service-token path for stable integrations and the human-login path only for short-lived local bootstrap.
Always test bridge health before testing tools.
Talk to Ledger Layer if you need help mapping setup choices back to your rollout and governed close workflow.
Every lease close, end to end,in one place.
Your team should not spend three days chasing workbook versions before quarter close. Ledger Layer gives controllers a governed path from source file to signed-off output, then leaves the audit trail intact when the rollout expands.