MCP (AI agents)

The LedgerBee MCP server gives AI agents (Claude, ChatGPT, Cursor, and other MCP clients) a curated tool set rather than an auto-generated wrapper around every REST endpoint. Transport is Streamable-HTTP; authorization is OAuth 2.1 with a browser sign-in. Add the server URL to your client and approve the sign-in — no API keys required.

One server per company

A LedgerBee MCP connection is scoped to exactly one company: the OAuth grant behind it binds to a single company, and every tool call runs against that company's books. Two URL forms exist:

The /c/{appCompanyId} discriminator exists for users with access to more than one company. MCP clients dedupe connections by URL and server name, so without it only one LedgerBee connection could be registered. With it, each company gets a distinct URL + server name pair (ledgerbee-{company}), and an agent can hold one connection per company side by side.

Marketplace → Connected apps in the LedgerBee app renders the setup below pre-filled for the company you're signed in to — URL, server name, and per-client commands, including a one-click Add to Cursor button and buttons that copy the URL and open Claude's and ChatGPT's settings.

Connect a client

Code
https://api.ledgerbee.com/api/v1/mcp

Code
claude mcp add --transport http ledgerbee --scope user https://api.ledgerbee.com/api/v1/mcp

Code
{
  "mcpServers": {
    "ledgerbee": {
      "url": "https://api.ledgerbee.com/api/v1/mcp"
    }
  }
}

Code
code --add-mcp '{"name":"ledgerbee","url":"https://api.ledgerbee.com/api/v1/mcp"}'

Code
codex mcp add ledgerbee --url https://api.ledgerbee.com/api/v1/mcp

Code
npx add-mcp https://api.ledgerbee.com/api/v1/mcp

Code
https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}

Code
claude mcp add --transport http ledgerbee-{company} --scope user https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}

Code
{
  "mcpServers": {
    "ledgerbee-{company}": {
      "url": "https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}"
    }
  }
}

Code
code --add-mcp '{"name":"ledgerbee-{company}","url":"https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}"}'

Code
codex mcp add ledgerbee-{company} --url https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}

Code
npx add-mcp https://api.ledgerbee.com/api/v1/mcp/c/{appCompanyId}

Anonymous developer server

/api/v1/mcp/developer is an anonymous server that exposes a single tool, read_development_docs, over the LedgerBee developer docs. Use it to verify your client setup before connecting the tenant server:

Code
claude mcp add --transport http ledgerbee-developer --scope user https://api.ledgerbee.com/api/v1/mcp/developer

The developer MCP endpoint in the API Reference renders the same install card with copy-paste setup for popular clients.

Tools

Every tool declares an inputSchema and an outputSchema, and every call returns its result twice: as structuredContent, the typed object the outputSchema describes, and as a text block carrying the same value as JSON. Parse structuredContent — for a tool whose result is wrapped, below, the two blocks carry different shapes. Read both schemas from tools/list, which is the live contract. Which tools appear there depends on the toolsets the connection has enabled; for a read outside them, reached through call_mcp_tool, call list_mcp_tools with response_format: "detailed", whose rows carry the same two schemas.

structuredContent is always an object. lookup_bookkeeping_rule returns a list of hits and get_business_entity_details returns null for an entity it cannot find, so those two values arrive wrapped as { "result": … }, which is what their outputSchema declares. Their text block carries the value unwrapped.

A connection reaches only what the user who authorized it can reach in LedgerBee. Each scope stands for the permission the app requires for the same data: subscriptions-read needs the subscriptions.read permission and the Subscription licence. The consent screen offers only the scopes the user's role covers, and every call checks the role as it is at that moment, so a scope stops working when the role stops covering it and works again when it does. A call the role does not cover is refused with that reason. Only an admin changing the role clears it; request_permissions cannot.

Read tools — available with the mcp:read scope on a tenant server; some also require the listed domain read scope:

Write tools — available with the mcp:write scope, or the listed domain write scope. Writes always require an OAuth grant:

Every tool names the toolset it belongs to, the resource it acts on and its operation. A toolset is the job a tool serves; the tools marked every connection belong to none and are always advertised. list, get, create, update and delete tools are named <operation>_<resource>; an action is a lifecycle step or lookup with no CRUD shape, such as booking a draft. A renamed tool stops answering to its old name in the same release.

This table is the full catalog. Call tools/list on the server for the tools your connection advertises, with each tool’s parameters and description.

A connection advertises the tools of its enabled toolsets plus the tools that belong to none. The toolsets are picked on the consent screen, which offers the ones the requested permissions can serve and ticks the recommended set — or, when a client re-authorizes a connection you already have, that connection's own set. An admin changes it afterwards under Settings → Integrations → OAuth clients → Connected apps, where each connection has a toolset checkbox per toolset; the change reaches the client the next time it reconnects. A toolset decides what the connection is shown, not what it may do: a read outside the enabled set stays reachable through call_mcp_tool, and what bounds a write is its scopes and the company's write policy. The page-control and dashboard-editing tools are off unless a connection enables ui or dashboards; their reads stay reachable through call_mcp_tool, and their writes need the toolset ticked on a hosted client. An agent asks for a toolset with request_permissions, the same call it uses for a missing scope.

MCP scopes are OAuth-only and cannot be assigned to API keys. Write tools always require an OAuth grant with the matching scope.

Discovery

Two tools search the catalog and reach a tool by name, so an agent never has to guess whether a capability exists. Both are advertised to every connection.

• list_mcp_tools searches the full catalog by keyword, toolset or kind. Each row carries the tool's name, toolset, resource, operation and description, and invokeVia: direct when the tool is in this connection's tools/list, call_mcp_tool when it is a read outside it, or enable_toolset when it is a write outside it, in which case enableToolset names the toolset to ask for. blockedReason carries the message tools/list puts on a tool the caller cannot invoke yet, or null when no gate is visible at list time. Called with no arguments it returns the toolset index; a query that matches nothing returns the index and the closest names rather than an empty list. response_format: "detailed" adds each tool's input schema and annotations.
• call_mcp_tool runs one read tool by name, with the target's own arguments under arguments, and returns that tool's own result. The target is checked exactly as a direct call: its scopes, licence, rate limit and AI budget apply, and a refusal carries the same message. A write tool is refused with its toolset named. Neither discovery tool can be run through it.

A wrapped call is recorded in the MCP audit log as call_mcp_tool:<tool>, with the target's route in targetOperation when the target is a facade tool. The usage statistics report the target under its own name and count the wrapped calls separately.

Resources

The server publishes your company's reference data as MCP resources, so a client can attach it to a conversation instead of spending a tool call on it every session. resources/list returns the ones this connection can read:

Each returns application/json, the same payload the matching tool returns — reading both gains nothing.

A read runs as the tool call it is: the same scopes, the same licence check, the same rate limit, and a row in the MCP audit log under resource:<name>. A resource therefore reaches nothing a tool would not, and a connection missing the scope or the toolset behind one is not shown that resource.

The company is in the URI because one person can connect several companies, and a client that keys a cache or a saved attachment by URI would otherwise hold two companies' charts under one name. A URI naming a company other than the one that consented to the connection is not found; it never resolves to yours.

Results carry a one-minute cache hint on protocol revision 2026-07-28, so an account or a VAT code you add is visible to the agent the next time it reads.

There are no resource templates. Every resource is fixed, and the only variable a template would have taken is the company, which your bearer token already decides.

Prompts

prompts/list returns three workflows a client turns into something you pick — a slash command in Claude Code and VS Code, an entry in the conversation in Claude.ai:

A prompt is text. It reads none of your data and calls no tool — it states the job and the order to do it in, and the agent then works through your tools under every gate that already applies, including the write policy. A prompt naming tools this connection is not served is left out of the list.

A host that collects no arguments still gets a usable brief: the step that needed the value says so, and the agent asks you.

Direct mode

The curated tools above cover the common accounting tasks. For everything else, the four tools on the public_api resource call the public REST API directly, as the connection's own access token. Any route the grant can already call over HTTP is reachable through them, and no other route is: the facade grants nothing on its own.

• Search finds routes by keyword. Each result carries the method, the path template, the required scopes, whether this connection can call it (callable), and curatedTool when a dedicated tool already covers the route.
• Details describes one route: path and query parameters, the request body schema, the success response shape, required scopes, and deprecation.
• Read performs a GET and returns the status and JSON body. A body longer than maxBytes (default 64 KB) is cut, and the result names the route's paging parameters.
• Write performs a POST, PATCH, PUT or DELETE. It takes a one-line summary of the change, shown on the approval card and kept in the audit log.

The agent searches first and uses the curated tool whenever one is named: the curated tools validate input, stage the change for review in LedgerBee, and can be reversed. The facade does none of that.

Enabling writes

Direct writes are off by default. Turn them on under Home → Hivey → Permissions, where the Direct API writes row takes one of three values.

The three read-side tools have no setting: a read the grant can perform over HTTP is not more dangerous when performed through MCP.

What Auto holds back

Auto commits in the call: the server asks the user nothing first. A curated tool's write that looks risky is staged instead, exactly as under Approval, and waits in the approval queue; the result carries autoCommitHolds naming each reason, and re-reading the proposal adds the same reasons as sentences in autoCommitHeldBecause. A write is held when:

A write with a blocker, and one that redirects money (a payment from an inbox booking, a supplier's bank account), waits for a person as it always has. The Write tool's direct requests are not covered by these rules: under Auto they run as sent.

Tools that drive your browser tab

Some tools act on a live LedgerBee tab and need one paired to the session; each says so in its description. When none is paired and the client declares URL elicitation, the call returns an input_required result asking the user to open a page rather than failing — the approval queue, the connection's permission editor, or the app itself, whichever the call needs them to reach. Retry once they have. A second retry that is still blocked returns the refusal instead of the link again.

Scopes

Search, details and read require mcp:read; write requires mcp:write and a user-consented grant. Every route also enforces its own scopes, exactly as it does for an HTTP client: a read of /v1/customers needs customers-read, and a write of POST /v1/customers needs customers-write. A call the connection cannot make with its scopes, as its user's role narrows them, is refused before any request is made, with the missing scope named. Search reports the same check as callable, so the agent can see which routes it can reach.

Idempotency

Every write call carries an idempotency key. When the agent passes idempotencyKey, that key is sent; otherwise the server derives one from the grant, the method, the route template and the request body. The result echoes the key as idempotencyKey and sets replayed: true when the API served the stored outcome of an earlier identical request instead of writing again. A retry after a timeout therefore creates no duplicate.

Excluded routes

Routes that manage authentication, single sign-on, API keys and the MCP endpoint itself (/v1/auth, /v1/oauth, /v1/api-key, /v1/scim, /v1/portal-sso, /v1/mcp) are never reachable through the facade, whatever scopes the grant holds, and neither is any write to /v1/webhook-endpoints: a webhook endpoint created under prompt injection would be an exfiltration channel. A request to one of them is refused with a message saying so.

Errors

A route that answers 400 or above does not fail the tool call. The result carries error: true, the status, and the route's own error body, so the agent can read a validation message and correct the request. The facade's own refusals raise a tool error: an unknown path, an excluded route, a missing scope, or direct writes set to Deny.

Audit

Every facade call is recorded in the MCP audit log with the tool name, the grant, the outcome, and targetOperation, the route it hit, as "POST /v1/customers". The loopback request carries the same request id as the MCP call, so the API request log and the MCP audit row share one id.

Endpoints

Authorization (OAuth 2.1)

The tenant-scoped servers follow the MCP authorization spec. A compliant client handles the whole flow on its own: it discovers the authorization server via .well-known, registers itself, and opens the browser sign-in. The metadata endpoints:

• /.well-known/oauth-protected-resource (and a per-company variant)
• /.well-known/oauth-authorization-server
• /.well-known/openid-configuration
• /.well-known/jwks.json

Clients that self-register use Dynamic Client Registration. An MCP client is a DCR-registered connected app — the same record backs both terms:

Code
POST https://api.ledgerbee.com/api/v1/oauth/register

A partner app that LedgerBee registers for you (rather than self-registering via DCR) runs the same authorization flow. See Connected Apps.

See Authentication for the full OAuth flow.