API keys and MCP access
Create a personal API key, connect an agent over MCP, and understand what the LedgerHQ authorize screen grants.
LedgerHQ is fully API- and MCP-driven: everything you can do in the app is also
reachable programmatically. The web UI, the REST API under /api/v1, and the
MCP server at /api/mcp are built to stay in parity, so an agent or integration
can do the same bookkeeping work a person does in the browser. This article
covers the two ways you connect that programmatic access — a personal API
key for scripts and REST clients, and the MCP flow for agents like Codex
and Claude — and what the authorize screen actually grants.
Both live on the API and MCP tab of your account dialog. Open it from the
user menu at the bottom-left of the app, or deep-link with ?account=api. The
tab is headed API keys, MCP, and plugins, with the key rule stated up top:
connections follow the same companies and bookkeeping permissions as the person
who creates them.
A key or token is a credential. Anyone holding it can act on your companies with your access. Store it in a secrets manager or environment variable, never in chat, in a commit, or in a shared document. This article never shows real key values, and neither should you.
Create A Personal API Key
Use an API key when you want a dependable, long-lived credential for a script or integration that calls the REST API directly. On the API and MCP tab, find the API keys card, type a Key name that describes where it will be used, and select Create API key.
LedgerHQ shows the full key exactly once, with the reminder that it will not be shown again — copy it immediately into your secret store. After that, the tab lists each active key by name and prefix only, with a control to revoke it. A counter shows how many keys you have against the maximum allowed.
Call the REST API with the key as a Bearer token. The base URL is shown right on the card:
https://ledgerhq.pro/api/v1By default a key carries full MCP access. If your account has advanced controls available, you can narrow a key to specific scopes when you create it:
- Read bookkeeping data — read-only access.
- Reports and exports — run and export reports.
- Bank feed coding and posting — code and post bank feed rows.
- Bank reconciliation — reconcile bank activity.
- Accounting writes and imports — create accounts, journal entries, imports.
- Settings, billing, integrations, and backups — administrative changes.
- Full MCP access — everything above.
Grant the narrowest scope that lets the integration do its job.
A LedgerHQ API key is not the same as an Anthropic or provider key. The API key authenticates a client to LedgerHQ's REST and MCP surface. The provider key that powers Tally is set separately — see Connecting your Anthropic API key and Hiring and configuring Tally.
Connect An Agent Over MCP
For MCP-native agents, the same tab has an MCP and plugin access section with guided setup for Codex, Claude, and other MCP clients. MCP lets an agent use LedgerHQ's packaged bookkeeping tools directly rather than calling raw REST endpoints.
There are two connection styles:
- A Codex connection token. Create a token labeled for the agent; LedgerHQ generates it once and provides the setup that stores it in a local token file on that computer. The token stays connected until you revoke it. New tokens default to read, reports, bank feed, reconciliation, and accounting-write scopes, and follow your current LedgerHQ access.
- The remote MCP server. Claude and similar clients connect to
https://ledgerhq.pro/api/mcpand sign in through LedgerHQ. In Claude Code that isclaude mcp add --transport http --scope user ledgerhq https://ledgerhq.pro/api/mcp; in Claude.ai, Desktop, or Cowork, add a custom connector pointing at the same URL. The tab provides copyable setup for each.
Once connected, you ask the agent for the bookkeeping work you want done — list the companies the firm manages, pull a profit and loss, suggest matches for unreconciled bank activity — and it uses the approved MCP tools to do it.
The MCP Authorize Screen
When an MCP client connects through the remote server, LedgerHQ shows an authorize screen titled Connect LedgerHQ that names the application asking to connect and lists exactly what it will be able to do:
- List the LedgerHQ companies this firm manages
- Read and manage your chart of accounts
- Read Plaid-connected bank activity
- Reclassify, reconcile, and exclude bank transactions
- Generate financial report packets
The connection is anchored to a firm account, not to a single company. If you belong to more than one firm, you choose which firm the connector authorizes; the connector then maps individual companies to the companies that firm manages. Select Authorize to approve, or Deny to reject. The flow uses OAuth 2.1 with PKCE and is an account-level connection.
Only authorize clients you trust — approving grants standing access to the chosen firm's books until you revoke it. MCP connections must be made from a firm workspace, and creating one requires active firm staff access. Review and revoke connections and tokens from the API and MCP tab whenever an integration is no longer needed.
What To Review
Keep the list of active keys, connection tokens, and MCP connections short and named for their purpose, so an unused credential is easy to spot and revoke. Because every connection inherits the creator's companies and permissions, create integrations under an identity whose access matches what the integration should reach — not broader. When you no longer recognize a key or connection, revoke it; a new one takes seconds to issue.