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. The API itself is documented in the
Developers section of this help centre.

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

Nothing is ever sent to your clients. Even with quotes:write, the assistant
can only create and edit quotes. Emailing a quote to a client, and marking one
accepted, stay actions you take yourself in Beeswax — there is no API route for
either, so no assistant can trigger them.

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. If you are removed from the account, your tokens for it stop working at once.
  • 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 quotes:write, journal_entries:write or tax_returns:write only if you want the assistant to be able to draft quotes, 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)
    • companies:read and transaction_accounts:read so it can look up clients, your chart of accounts and your tax codes. Treat transaction_accounts:read and transactions:read as part of the core set — together they unlock the per-account ledger tool, which is what any reconciliation or tax-return check uses. Without them the assistant gets a 403 the moment it tries; asking it to check the Beeswax connection lists exactly which scopes are missing.
    • 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 project_documents:read if you want it to read project documents, and project_documents:write if it should draft and edit them — the assistant can then write a proposal straight into a project, with every edit landing in the document's version history under your name.
    • Add themes:read / themes:write if you want it to author custom document themes: it reads the theme specification, writes the theme, validates and previews it, and can switch your account between any theme.
    • Add quotes:write, journal_entries:write, tax_returns:write and/or transaction_templates:write only if you want the other write tools — building quotes, drafting and posting manual journals, editing tax-return figures, or maintaining your products & services catalogue (see What the assistant can do). To build quotes, quotes:write needs companies:read, projects:read and transaction_accounts:read alongside it — a quote has to name a client, a project, and an account for each line. transaction_accounts:read also covers your tax codes, which is what lets it price a new product correctly. Add transaction_templates:write if you want it to create the products those lines are priced from.
    • 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@latest, 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. Flip the toggle at the top of the extension's settings from Disabled to Enabled. A newly installed extension arrives switched off, and saving the token does not switch it on. Until you enable it, the extension appears in Settings → Customize → Connectors with a — status and exposes no tools at all — a saved token makes no difference.
  5. 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@latest"],
      "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@latest
  • 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. You can also ask
"check my Beeswax connection" — a built-in health check that reports the connected
account, the token's permissions, and whether the connector is up to date. If Claude
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@latest"],
      "env": {
        "BEESWAX_API_TOKEN": "token-for-steam-uk"
      }
    },
    "beeswax-acme": {
      "command": "npx",
      "args": ["-y", "beeswax-mcp@latest"],
      "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.

How each connection appears in Claude Desktop

Everything you have connected is listed under Settings → Customize → Connectors.
You can't add the Beeswax server from that screen — its Add custom connector
button is for remote, URL-based services — but once it's set up locally, it is listed
there alongside them. Manual entries and the one-click extension both show up, but
they are labelled differently:

What you installed Listed as Type Badge
A manual claude_desktop_config.json entry the JSON key you gave it — beeswax, beeswax-acme, … Desktop Local dev
The one-click extension Beeswax — the name built into the extension Desktop none

The status beside each one is what tells you whether it is actually working:

  • ✓ — the server is running and its tools are available to the assistant.
  • — — the server is disabled or not running. It exposes nothing, even with a valid token saved against it.

Running two accounts side by side

The extension and any number of manual entries can be enabled at the same time.
Tools are namespaced by the server's name, so the assistant sees one parallel set of
Beeswax tools per connection — one under beeswax, another under beeswax-mcp, and
so on.

There is no priority and no fallback. The assistant sees every tool from every
enabled server, and nothing at all from a disabled one. If only one Beeswax server is
enabled, that is the only account it can reach — regardless of what any other entry
has configured.

Naming them clearly

The extension's name comes from the extension itself and cannot be changed in the
app — it is always listed as "Beeswax". That leaves two sensible patterns:

Pattern How it reads Trade-off
All manual entries, each with an account-specific name (beeswax-acme, beeswax-steamuk) Every account carries its own name, both in the Connectors list and in the tool names the assistant sees. Clearest to work with, but every token sits in plain text in claude_desktop_config.json.
Extension for your main account + manual entries for the others Your main account is "Beeswax"; the rest carry their own names. The main account's token stays in your operating system's keychain, but that account shows under the generic name "Beeswax" rather than its own.

If you set up with the default beeswax entry, rename it to something
account-specific as soon as you add a second account — a plain beeswax sitting
next to beeswax-acme is exactly the pair that gets confused. Renaming is just
changing the JSON key, then restarting Claude Desktop.

Working safely with more than one account connected

  • Say which account you mean. Open the request with the account — "in Acme, list the overdue invoices" — rather than leaving the assistant to infer it.
  • Check before you write. Before anything that changes data — a quote, a manual journal, a tax-return figure — ask the assistant to "check my Beeswax connection" on that server first. The health check names the account the server is bound to, so you can confirm you are about to write to the right one.
  • Identify by account id if the name doesn't help. The health check reports both an account id and a name. Some accounts carry an internal-looking name, so if the name isn't one you recognise, match on the id instead.
  • Turn off what you're not using. If today's work is only about one client, disable the other Beeswax servers for the session — a disabled server can't be reached by mistake.

Cowork sessions and cloud sessions linked to your computer

A Cowork task, or any cloud session linked to your computer, keeps the set of MCP
servers that existed at the moment it linked. Adding a server, enabling one, or
reconfiguring one does not reach a session that is already running — it keeps
reporting the old set of tools no matter how long you wait.

To make a running session pick up the change:

  1. Fully quit and reopen Claude Desktop.
  2. Then either wait for the task to re-link, or open the task in the app and choose Link to this computer.

Starting a new task also works, and is usually quicker.

The same applies to changing the token inside an entry you already have: the server
reads its token once, when it starts, so a new token only takes effect after the app
is restarted.

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. With invoices:write: create an invoice (it lands as a draft), edit it, add or change lines, finalise it, void a finalised unpaid one, and view or restore its version history. It cannot email the invoice.
Quotes List, view, and see postings. With quotes:write: build a whole quote in one go — the phases and every line — then edit it, reorder the phases or lines, and move it out of draft. Lines can be priced from your products & services catalogue, which also gives each one its colour on the quote's Gantt preview. It cannot email the quote or mark it accepted.
Expenses List, view, postings; filter by overdue or outstanding. With expenses:write: the same create, edit, finalise, void and version-history tools as invoices, plus the supplier's reference number, and attaching receipts (the assistant sends the file inline).
Payments List/search payments, view one, and see what each payment applies to. With payments:write: apply a payment from a bank account to one or more finalised invoices or expenses (all-or-nothing, every payment rule enforced), and remove a payment.
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, compare with a prior year, and read the notes and discussion on a return. With tax_returns:write: create or repopulate a return, override a field's value, record a note against a field explaining a figure, post to the return's discussion, confirm a section, and finalise — the same as working on the return in the web form. The assistant is the reviewer: there is no separate automated review to run.
Projects List your active projects and view one's details.
Clients & suppliers List the companies on your account, so a client can be named by name rather than by id. With companies:write: add a new client or supplier (with its contact people) and update an existing one — so an invoice for a brand-new client no longer needs a trip to the web app first.
Chart of accounts List your transaction accounts — needed to say which account a document line bills to — and pull one account's ledger for a period: posted postings only, with opening balance, running balance and closing balance, which is how to reconcile an account or check a tax-return figure in one call.
Milestones List and view project milestones.
Products & services List and view your catalogue — prices, units, categories, and the income/expense accounts and taxes behind each item. With transaction_templates:write: add an item, correct one filed against the wrong income or expense account, reprice it, or archive it. Every item must name its accounts explicitly and they are type-checked, so nothing lands on a wrong-side account.
Time entries List and view logged time.
Calendar events List and view events visible to the token's user.

Everything outside the write areas above is strictly read-only. Nothing the assistant
does can email a client, mark a quote accepted, or move a finalised invoice or expense
back to draft. Invoices and expenses it creates land as drafts, invisible to the ledger,
your GST/VAT reporting and Xero until finalised — so a draft the assistant gets wrong
costs nothing. Publishing a catalogue item to your public rates card also stays a click
in the web app.

The ledger rule. Every entry the assistant sees carries a posted flag, and an entry
is on the ledger only when it is true. Drafts, payroll templates, quotes and voided
entries never are, whatever their state or number. From connector version 1.4.0 the
listing tools return posted entries only unless asked for drafts, and a draft's postings
come back empty — so the assistant cannot mistake a draft or a payroll template for real
activity when it sums up your books.

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 quotes:write, transaction_templates:write, journal_entries:write or tax_returns:write when you actually want the assistant drafting quotes, maintaining your catalogue, 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.

Updating

The connector is a small program that runs on your computer — it is separate from
Beeswax itself. Beeswax updates instantly for everyone, but your local connector only
changes when your computer fetches a new copy. When we release new abilities (a new
tool, a new field on an existing tool), an out-of-date connector simply doesn't have
them — and the assistant can't use what it doesn't have.

Three things keep you current, and none of them need you to remember anything:

  1. The assistant tells you. Every time the connector talks to Beeswax, Beeswax tells it what the newest version is. If yours is older, the assistant is asked to let you know in the chat, with a link back to this section.
  2. You can ask any time. Say "check my Beeswax connection" in a chat. The assistant runs a health check and reports the version you're running, the newest version, whether you're up to date, which account is connected, and what the token is allowed to do.
  3. The config updates itself. If you set the server up with beeswax-mcp@latest (all the examples on this page do), your app fetches the newest release each time it starts — restarting the app is the whole update.
  4. We email you. The Claude Desktop extension can't update itself, so the first time an out-of-date connector talks to Beeswax after a new release, the owner of that API token gets one email with the steps below — one per release, per token, never more.

How to check your version

  • Ask the assistant: "check my Beeswax connection" — works in every app.
  • Claude Desktop extension: Settings → Extensions shows the installed version next to Beeswax.
  • Terminal: npx -y beeswax-mcp@latest --version prints the newest release's version number.

How to update

How you installed How to update
Claude Desktop one-click extension Download the current beeswax-mcp.mcpb and install it over the old one (your saved token is kept). Then start a new chat.
Config file with beeswax-mcp@latest Fully quit and reopen the app — it fetches the newest release on launch.
Config file with plain beeswax-mcp (older setups) Edit the config once: change the argument to beeswax-mcp@latest. From then on, restarting the app is the whole update.

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 It is almost certainly still disabled. A newly installed extension arrives switched off, and saving the API token does not switch it on — open its settings and flip the toggle at the top from Disabled to Enabled. Until you do, Settings → Customize → Connectors lists it with a — status and it exposes no tools at all. Once it shows ✓, start a new chat — existing chats don't pick up new tools.
I enabled or added a server but my Cowork session still can't see it A Cowork or cloud session that is linked to your computer keeps the servers it had when it linked. Fully quit and reopen Claude Desktop, then re-link the task (or just start a new one) — see Cowork sessions and cloud sessions linked to your computer. Changing a token in an existing entry needs the same restart.
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@latest"]. 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 says an update is available, or seems to run an old version See Updating above — with beeswax-mcp@latest, restarting the app is the whole update; extension users re-download the file.
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, or the person who created it has left the account. Create a fresh one (as someone who still belongs to the account) 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