Connect your agent

Analytical Ledger exposes your books through MCP, the Model Context Protocol. You bring the agent: your own Claude, ChatGPT, OpenAI Codex or any compatible client. The ledger supplies scoped accounting tools, not an AI subscription.

Ask it things like "Why are travel expenses over budget?" or "Prepare a balanced draft for this month's software accrual." You review the evidence, and any draft, in Ledger.

Before you connect

1. Sign in to your own instance as an active owner. Turn on owner authentication before you expose a local install to any network.
2. Open Settings → Agents and connect the card that matches your client. Start with Read, the default. Choose Read + Draft only when you need drafts.
3. Work out your server URL: your instance's origin plus /api/mcp.
4. Start OAuth from the client. Sign in to Ledger in the browser, review the requested scopes, connection, entities and fiscal year, then consent. Creating a card alone does not authenticate the client.
5. Ask for the current context first, and confirm its entities and year before you ask financial questions. A new scope or a new year needs a new authorization.

Replace the example hostname and port with yours. On the local Windows app the port can change at each launch; use the address shown in the app window. A phone's localhost means the phone, not your PC.

The issuer is one canonical origin from AUTH_URL. Production requires HTTPS. A local install (LEDGER_DEPLOYMENT=local) also accepts HTTP on localhost or 127.0.0.1.

Read and draft scopes

There are exactly two scopes. The connection's saved access is a ceiling: OAuth can never grant more than the card allows.

Read tools include al_current_context, al_entities_list, al_trial_balance, al_profit_and_loss, al_cash_forecast, al_budget_vs_actual, al_period_close_status, al_ap_bills, al_ar_invoices, al_pending_approvals and al_tax_rollup, among others. They return only what falls inside what you authorized.

Drafts wait for a person. A draft appears in Ledger unposted. A person reviews it and approves or posts it through the normal accounting controls. No agent token can post or approve, even if a model asks it to.

The MCP endpoint does not expose posting, approval, closing or locking a period, payments, filing, arbitrary SQL, repository execution, batch drafts or user administration. A database guard, trg_assistant_approval_guard, backs that up.

Existing read connections do not gain draft access when the catalog changes. To change access, disconnect, reconnect and authorize again.

Claude Code

After you create the Claude card, add your instance. Replace 3000 for a local install, or use your HTTPS URL for a hosted one.

PS>claude mcp add --transport http ledger http://127.0.0.1:3000/api/mcp

1. Open Claude Code and run /mcp.
2. Select Ledger and authenticate in the browser.
3. Check the entity and year, and consent to the scopes.
4. Run claude mcp list to see the connection status.

To pin read access, set the HTTP entry's oauth.scopes to "ledger.read". For drafting, use "ledger.read ledger.draft" with a Read + Draft connection. Do not paste access tokens into headers or config files.

The command and flow were checked against Claude Code's MCP documentation on 2026-10-26. A full live sign-in has not been tested.

OpenAI Codex CLI

Preview After you connect the OpenAI Codex card, add this to ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows). Use your HTTPS URL for hosted access.

[mcp_servers.ledger]
url = "http://127.0.0.1:3000/api/mcp"
scopes = ["ledger.read"]

Or add the server from the command line, then log in:

PS>codex mcp add ledger --url http://127.0.0.1:3000/api/mcpPS>codex mcp login ledger --scopes ledger.read --oauth-client-registration dcr

Complete Ledger's browser consent. For drafts, choose a Read + Draft connection, set scopes = ["ledger.read", "ledger.draft"], and log in again with --scopes ledger.read,ledger.draft.

Ledger supports dynamic client registration (DCR), which is why the login selects it. It does not support Client ID Metadata Documents. Older Codex releases may lack the DCR flag. Syntax was checked against OpenAI's MCP documentation on 2026-10-26; a full live sign-in has not been tested.

Claude and ChatGPT

Both connect through the vendor's cloud, so they need a publicly reachable HTTPS instance. Even Claude Desktop connects through Anthropic's cloud and cannot reach your PC's loopback address. For a local install, publish it first with Your agent in your pocket.

Claude Desktop and claude.ai

1. On claude.ai, open Customize → Connectors → Add → Add custom connector.
2. Name it Ledger and enter https://books.example.com/api/mcp.
3. Choose OAuth sign-in and Register automatically for the OAuth client, not Claude's published identity.
4. Connect, sign in as the Ledger owner and complete Ledger's consent.
5. Enable the connector in a conversation's tools menu. Use the same Claude account in Desktop. Team and Enterprise owners may need to add and allow it first.

This is a remote custom connector, not a claude_desktop_config.json stdio server. Labels and availability depend on your plan and version, and no directory listing is claimed.

ChatGPT

1. Create the ChatGPT card in Ledger, and use an HTTPS instance or tunnel.
2. On ChatGPT web, open Plugins → + → Add custom MCP server.
3. Enter a name and the full https://books.example.com/api/mcp URL, and choose OAuth.
4. Review permissions, create the connection and complete Ledger's owner consent.
5. Install or enable it in a new chat by typing @.

Workspace policy may require admin approval. Older ChatGPT versions call these Apps or Connectors and may require developer mode; that older menu path is unverified here. Never choose unauthenticated access. If custom MCP is unavailable on your plan, use another client.

Both paths were checked against the vendors' current guides on 2026-10-26. A live Desktop or ChatGPT sign-in has not been tested.

Other MCP clients

Preview Choose Other MCP client in Ledger's agent settings, then:

1. Configure a Streamable HTTP server at your instance's /api/mcp.
2. Use the OAuth authorization-code flow with S256 PKCE, dynamic client registration and token_endpoint_auth_method=none. Do not send a client secret.
3. Discover /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-authorization-server on the same origin.
4. Send resource=<your-origin>/api/mcp in authorization and token requests. Request ledger.read, and add ledger.draft only if you need it.
5. Finish owner consent, then call tools/list to check the connection.

Send Content-Type: application/json and Accept: application/json, text/event-stream with the OAuth bearer token. The server is stateless Streamable HTTP over POST /api/mcp and answers in JSON; there is no SSE stream and no session ID, and GET and DELETE are refused. Token and registration requests that carry a browser Origin header are rejected.

A client that needs legacy SSE, implicit flow or a static API key is not compatible.

Approval, audit and revoking

• Humans post. The agent can stop at a draft. Posting and approval stay with people, enforced in the database.
• Owner-bound tokens. Codes are single use, redirects must match exactly, and tokens are bound to <your-origin>/api/mcp. Access tokens last one hour and refresh tokens rotate. Deactivating or demoting the owner, or losing an entity permission, invalidates access.
• Audit. Every MCP request is written to mcp_access_audit with the method or tool, the outcome (ok, denied, unauthorized, invalid, rate_limited or error), the HTTP status, the connection, a hash of the arguments and any resulting draft ID. Raw bearer tokens and raw arguments are not stored there.
• Rate limits. 60 authenticated requests per token per minute window. Over the limit you get a 429 with Retry-After: 60. Dynamic registration is capped at 60 clients per minute across the instance.
• Revoke. Settings → Agents → Disconnect revokes the connection, its tokens and unused codes, and ends unfinished runs. Remove the connector from the client as well: deleting only the client's configuration is not server revocation.
• Data sharing. The client and its model provider can receive the scoped financial data they read. Review their retention settings. Memos, vendor text and queued requests are untrusted data, not instructions to widen access.