Let AI agents read and write your books, with scoped access

What is the ClearBooks MCP server?

The MCP server exposes ClearBooks as tools an AI client can call. According to the generated reference, it currently offers more than 300 tools across 45 resource groups, of which roughly 40% write data. They cover transactions, bank accounts and reconciliation, invoices and bills, customers and vendors, the chart of accounts and journal entries, financial reports, payroll, tax forms, the cap table and data rooms, receipts, budgets, forecasts and more.

It uses the streamable HTTP transport at a single endpoint:

POST https://nwuiorqmvkhxjzjrvnxf.supabase.co/functions/v1/mcp-server
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: cb_live_your_api_key_here

An agent should call tools/list first. It returns each tool's JSON Schema, including required arguments, so the agent works from the real contract rather than guessing. When no specific tool fits, the ask_agent tool hands a natural-language request to the full ClearBooks AI agent under the same scopes, at a cost of one AI credit per call.

How do I connect Claude, Cursor or another MCP client?

Create an API key in the ClearBooks Developer Portal, grant it the scopes you want, then add the server to your client.

Claude Code:

claude mcp add --transport http clearbooks https://nwuiorqmvkhxjzjrvnxf.supabase.co/functions/v1/mcp-server \
  --header "x-api-key: cb_live_your_api_key_here"

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "clearbooks": {
      "url": "https://nwuiorqmvkhxjzjrvnxf.supabase.co/functions/v1/mcp-server",
      "headers": { "x-api-key": "cb_live_your_api_key_here" }
    }
  }
}

Claude Desktop and Windsurf connect through the mcp-remote bridge (npx -y mcp-remote with the same URL and header). Any other client, including your own agent or a ChatGPT integration that speaks MCP, can POST JSON-RPC to the endpoint directly. Full setup for each client is in the docs.

How are permissions and security handled?

Access is designed so an agent can only do what you allowed:

• Scoped keys. Every tool declares one scope in the form clearbooks:resource:read or clearbooks:resource:write, for example clearbooks:invoices:write or clearbooks:payroll:read. Write does not imply read, and a key with no scopes is refused every tool.
• Clear errors. Calling a tool the key does not cover returns an error naming the missing scope, so the agent can tell you what to grant instead of failing silently.
• One organization per key. The organization is resolved from the credential. No tool takes an organization argument, so an agent cannot reach another company's books.
• Read-only sessions. A signed-in user's session token can be used instead of a key, but it only grants read access. Writing always requires an API key with an explicit write scope.
• Books stay protected. Accounting rules are enforced in the database, not only in the app. A hard-closed period refuses postings from the API and the agent just as it does from the app, and journal entries must balance.

See reconciliation and close for how period locks work.

The REST API

The same key works on the REST API, and the scope strings are identical on both, so one key means the same thing everywhere. The base URL is:

https://nwuiorqmvkhxjzjrvnxf.supabase.co/functions/v1/clearbooks-api/v1

Conventions:

• Authentication with the x-api-key header. Missing or invalid keys return 401; a missing scope returns 403.
• JSON everywhere, UUID identifiers, and ISO 8601 dates.
• Pagination with limit (default 100, max 1,000) and offset, with a total count in each response.
• Rate limits per key, reported in X-RateLimit-Limit and X-RateLimit-Remaining headers, with 429 and Retry-After when exceeded.
• Request IDs in X-Request-Id on every response for support.

Webhooks can notify your system when transactions are created, updated or deleted; when invoices are created, sent, paid or become overdue; when customers or bills change; and when payments are received. Deliveries are signed with HMAC-SHA256 so you can verify them. The full endpoint reference is on the API page.

What can an agent actually do with it?

Some examples of work an agent can complete end to end with the right scopes:

• Categorize a month of bank transactions and flag the ones it is unsure about.
• Start a bank reconciliation, auto-match an imported statement against the books, clear the remaining items and finish once the difference is zero. (Uploading the statement file itself is done in the app.)
• Draft, send and record payment on invoices, or set up a recurring invoice.
• Create and approve a payroll run and record the tax deposit.
• Pull a profit and loss, balance sheet or trial balance and explain changes from last quarter.
• Draft Form 1120 figures for the year and list what still needs review.
• Close last month so nothing else can be posted to it.

The in-app AI bookkeeper uses the same tools, so anything the agent inside ClearBooks can do, an outside agent with the right key can do too.

Who is it for?

Founders who already work with Claude, ChatGPT or Cursor and want their agent to handle bookkeeping directly; developers building internal tools or automations on top of their company's books; and accountants who want to script repetitive cleanup. If you are moving from another system, see how ClearBooks compares with QuickBooks and Xero.

Frequently asked questions