Connect to Claude & AI Assistants (MCP)

Set up the Beeswax MCP server in Claude Desktop, Claude Code, or any other MCP-capable app so AI assistants can work with your account data.

Overview

The Beeswax MCP server lets an AI assistant — Claude Desktop, Claude Code,
or any other MCP-capable app — read your Beeswax data: invoices, quotes, expenses,
payments, ledger transactions, manual journals, projects, time entries, calendar
events, milestones, products & services, and (Australian accounts) tax returns. You can ask questions in
plain English like "which invoices are overdue?" or "what did we bill on the
Hadestown project last month?"

It uses MCP (Model Context Protocol), an open
standard for connecting AI assistants to external tools and data. The Beeswax MCP
server is a thin wrapper around the Beeswax API — every question the assistant asks
becomes a normal, authenticated API call.

Read-only by default. With read scopes, the MCP server can only view your
data. A small set of write tools exists — creating and posting manual journals,
and editing tax-return figures — but they work only if you grant the matching
journal_entries:write / tax_returns:write scopes when you create the token.
Leave the write scopes unticked and the connection cannot change anything.

How access works (important)

Access is controlled entirely by an API token, the same kind you create for
Zapier or N8n. Three things follow from this, and they are the key to understanding
the security model:

  • One token = one account. Every token is permanently tied to a single Beeswax account. The assistant never chooses the account — there is no "account" setting in any request. Whatever account the token belongs to is the account the assistant sees, and nothing else.
  • You can only create a token for an account you belong to. Beeswax refuses to issue a token for an account you are not a member of, so an assistant can never reach data you don't already have access to.
  • Scopes limit what it can do. A token only grants the permissions (scopes) you tick when you create it. For a read-only connection grant only read scopes; add journal_entries:write or tax_returns:write only if you want the assistant to be able to draft manual journals or edit tax-return figures.

To let an assistant work with more than one account, you create a separate token
per account and add a separate server entry for each — see
Connecting more than one account below.

Before you begin

You'll need:

Requirement Notes
An MCP-capable app Claude Desktop, Claude Code (terminal, desktop app, or IDE extension), Cursor, VS Code, and most other AI desktop apps support MCP. Setup for each is in Step 2 below.
A Beeswax API token Created in Account Settings → API Tokens (Owners / Super Admins only).
Node.js 18 or newer Claude Desktop users can skip this — the one-click extension below includes everything. Only the other apps need Node; check with node -v.

That's the whole list. Claude Desktop users install a single downloaded file; every
other app fetches the server automatically from npm
(beeswax-mcp) the first time it starts.

Local server, not a "Custom Connector." The Beeswax MCP server runs locally
on your computer — it has no web address. In Claude Desktop that means you add it
through the Developer config file (described below), not the Connectors
screen, which is only for remote services. The same applies everywhere: it works in
desktop apps that can launch a local process, but can't be added to web or mobile
apps that only accept a connector URL.

Step 1 — Create a read-only API token

  1. Go to Account Settings → API Tokens.
  2. Click New Token and give it a clear name, e.g. "Claude Desktop — read only".
  3. Under scopes, grant only the read scopes the assistant needs. A good read-only set is:
    • invoices:read, quotes:read, expenses:read, payments:read, transactions:read, journal_entries:read
    • projects:read, milestones:read, time_entries:read, events:read, transaction_templates:read (products & services)
    • tax_returns:read if you want it to read tax returns (Australian accounts).
    • Add accounts:read if you want it to confirm which account it is connected to.
    • Add journal_entries:write and/or tax_returns:write only if you want the write tools — drafting and posting manual journals, or editing tax-return figures (see What the assistant can do).
    • Choose all only if you specifically need the journal-entries reader for long-tail document types (payrolls, credit notes, bank transfers) — all grants full read and write access, so prefer the narrow scopes above.
  4. Save, then copy the token immediately — it is shown only once.

See API Tokens for the full reference on scopes and token management.

Step 2 — Add the server to your app

Pick the app you use. Claude Desktop has a one-click installer — start there if
that's your app. Every other app takes the same three values: the command npx,
the argument -y beeswax-mcp, and one environment variable — your token.
(npx comes with Node and downloads the server from npm automatically the first
time it runs.)

  1. Download the Beeswax extension: beeswax-mcp.mcpb
  2. Double-click the downloaded file (or drag it into Claude Desktop's Settings → Extensions screen). Claude Desktop shows the extension's details — click Install.
  3. In the settings form that appears, paste your API token from Step 1 and save. Leave Beeswax API URL as it is.
  4. Start a new chat — you're done.

Two things this path does better than any config file: it needs no Node.js at
all (Claude Desktop runs the extension with its own built-in runtime), and the
token is stored by the app in your operating system's keychain, not in a
plain-text file. To update later, download the newer file and install it over the
old one; to remove it, use Settings → Extensions.

Claude Desktop — manual config (alternative)

Prefer the config file? This works too:

  1. Open Claude Desktop's Settings → Developer → Edit Config. This opens a file called claude_desktop_config.json:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add a beeswax entry under mcpServers (merge with anything already there):
{
  "mcpServers": {
    "beeswax": {
      "command": "npx",
      "args": ["-y", "beeswax-mcp"],
      "env": {
        "BEESWAX_API_TOKEN": "paste-your-token-here"
      }
    }
  }
}
  1. Save the file, then fully quit and reopen Claude Desktop — it only reads the config on launch. The first start takes a few extra seconds while npx downloads the server; after that it's instant.
  2. If the app reports it can't find npx, replace "npx" with its full path — run which npx (macOS/Linux) or where npx (Windows) in a terminal to find it.

Claude Code

Claude Code — the terminal CLI, its desktop app, and the VS Code / JetBrains
extensions all share one configuration — registers MCP servers with a single command.
In a terminal, run:

claude mcp add beeswax \
  --env BEESWAX_API_TOKEN=paste-your-token-here \
  -- npx -y beeswax-mcp
  • By default the server is registered for the current project folder only. Add --scope user to make it available everywhere on your machine.
  • Avoid --scope project for this server — that writes the config (including your token) to a .mcp.json file inside the project, which is meant to be committed and shared.
  • Check it worked with claude mcp list — the beeswax entry should show as connected — or type /mcp inside a Claude Code session.

Other MCP apps (Cursor, VS Code, and more)

Any desktop app that supports local (stdio) MCP servers can run the Beeswax
server with the same command, argument, and environment variables:

App Where to add it
Cursor ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) — same mcpServers JSON shape as Claude Desktop above.
VS Code (Copilot agent mode) .vscode/mcp.json — uses a servers key instead of mcpServers, with the same command/args/env inside.
Anything else Look for "MCP servers" in the app's settings or documentation and supply the same three values.

Two advanced options. The server talks to https://app.beeswaxapp.com by
default; an optional BEESWAX_BASE_URL environment variable exists for pointing it
at another instance. And if you're a developer working on Beeswax itself, you can
run the server from source instead of npm — see mcp/README.md in the codebase.

Step 3 — Check it's working

In a new chat in whichever app you connected, ask something simple, e.g.:

"Using Beeswax, list my overdue invoices."

Claude should call the Beeswax tools and answer with your real data. If it can't see
the tools or reports an error, see Troubleshooting.

Connecting more than one account

Because each token is tied to one account, you connect multiple accounts by adding
one server entry per account, each with its own token. Give them distinct names
so you (and the assistant) can tell them apart:

{
  "mcpServers": {
    "beeswax-steamuk": {
      "command": "npx",
      "args": ["-y", "beeswax-mcp"],
      "env": {
        "BEESWAX_API_TOKEN": "token-for-steam-uk"
      }
    },
    "beeswax-acme": {
      "command": "npx",
      "args": ["-y", "beeswax-mcp"],
      "env": {
        "BEESWAX_API_TOKEN": "token-for-acme"
      }
    }
  }
}

Now you can ask "list invoices for Acme" or "...for Steam UK" and the assistant
will use the matching connection. This is the recommended pattern for bookkeepers and
accountants who manage several client accounts. (In Claude Code, do the same with two
claude mcp add commands using distinct names.)

Note: the one-click Claude Desktop extension connects one account (it has a
single token field). To connect several accounts in Claude Desktop, use the manual
config above — the extension and manual entries can coexist.

What the assistant can do

Each tool maps to one Beeswax endpoint:

Area What you can ask about
Invoices List, view, and see the ledger postings behind an invoice; filter by overdue or outstanding.
Quotes List, view, and see postings.
Expenses List, view, postings; filter by overdue or outstanding.
Payments List/search payments, view one, and see what each payment applies to.
Journal entries Search the ledger across document types and view postings (needs the all scope for a bare search or long-tail types).
Manual journals List and view manual (general) journal entries. With journal_entries:write: create a manual journal (balanced debits and credits, optionally as a draft) and post a draft to the ledger.
Tax returns (Australian accounts) List returns, view a return's sections and figures, see the transactions behind a field, and review AI findings. With tax_returns:write: override a field's value or confirm a section — the same as editing the return in the web form.
Projects View a single project's details.
Milestones List and view project milestones.
Products & services List and view your catalogue of products and services — prices, units, categories, and the income/expense accounts and taxes behind each item.
Time entries List and view logged time.
Calendar events List and view events visible to the token's user.

Everything outside the two write areas above is strictly read-only — the assistant
cannot create, change, or delete invoices, expenses, payments, or any other record.

Dates can be written naturally (e.g. "Jan 1 2026" or "2026-01-01"), and lists are
gathered across all pages automatically, so a single question like "what's overdue?"
returns the whole answer.

Security best practices

  • Treat the token like a password. With the manual configs it lives in plain text inside the app's config file (claude_desktop_config.json, ~/.claude.json, mcp.json, …), so anyone who can read that file can read your account data. Protect the file accordingly, and never commit a config file containing the token to a shared repository. (The one-click Claude Desktop extension avoids this — it stores the token in your operating system's keychain.)
  • Grant the narrowest scopes that work. Read-only scopes mean a leaked token can only view data, never change it. Avoid all unless you truly need it.
  • Leave write scopes off by default. Only add journal_entries:write or tax_returns:write when you actually want the assistant drafting journals or editing tax returns — and consider a separate, short-lived token for that work.
  • Set an expiry for temporary or experimental connections so the token stops working on its own.
  • Revoke when done. Remove the token in Account Settings → API Tokens the moment a connection is no longer needed — this takes effect immediately.
  • Subscription-linked. If the account's subscription lapses, its tokens are revoked automatically and the connection stops working.

Troubleshooting

Symptom Likely cause / fix
The .mcpb file won't install / Extensions screen is missing Update Claude Desktop — extensions need a recent version. Settings → check for updates, or reinstall from claude.ai/download.
The extension is installed but Claude doesn't use it Check it's enabled in Settings → Extensions, and that the API token was saved in its settings. Then start a new chat — existing chats don't pick up new tools.
The app doesn't show any Beeswax tools Config not loaded — fully quit and reopen the app (Claude Desktop only reads the config on launch). Check the JSON is valid (no trailing commas) and that args is exactly ["-y", "beeswax-mcp"]. In Claude Code, run claude mcp list to see the server's connection status.
"Server failed to start" / npx not found / spawn npx ENOENT Desktop apps don't always see your terminal's setup. Replace "npx" in the config with its full path (which npx / where npx shows it).
It starts, then errors the first time you ask a question Node too old — npx runs whatever node it finds first, and versions below 18 fail on the first request. Confirm node -v is 18+, or point the command at the npx beside a newer Node.
The assistant seems to run an old version of the server npx caches the download. Change the argument to beeswax-mcp@latest to force the newest release, then restart the app.
Works in one app but not another Each app is configured separately — Claude Desktop reads claude_desktop_config.json, Claude Code uses claude mcp add, Cursor and VS Code have their own files. Add the server in each app you use.
"Invalid or expired token" The token was revoked, expired, or mistyped. Create a fresh one and paste it again.
"Insufficient permissions. Required scope: …" The token is missing a scope the request needs. Edit the token and add the listed scope (or use all for the journal-entries reader).
Tax-return tools error or return nothing Tax returns are available on Australian accounts only, and need the tax_returns:read scope.
It connects but returns the wrong account's data A token only ever sees its own account. You've used the token for a different account — swap in the right one, or add a second server entry.
Connection stops working suddenly The account's subscription may have lapsed (tokens auto-revoke), or the token was revoked.

Permissions by role

Action Owner Super Admin Manager Accountant Basic Client
Create / manage API tokens for MCP Yes Yes No No No No

Only Owners and Super Admins can create the API tokens that MCP relies on, and
token management is included with every plan — Free included — and during the trial. Once a token
exists, anyone you give it to can use it from their own computer — so share it
carefully.

Browse Topics