MCP: BillOS for AI agents

One line of config puts BillOS inside Claude, Cursor, or anything else that speaks MCP. The agent can then issue a document, record an expense and read the numbers, in the user's own words, through the same key, the same limits and the same ledger as every other call here.

Connect

The endpoint is https://api.billos.co.il/mcp, Streamable HTTP, authenticated with your normal API key (X-Api-Key, or Authorization: Bearer bk_... for clients that only speak Bearer). A bk_test_ key talks to the sandbox exactly as it does over REST.

{
  "mcpServers": {
    "billos": {
      "url": "https://api.billos.co.il/mcp",
      "headers": { "X-Api-Key": "bk_live_..." }
    }
  }
}

For a desktop client that only launches local processes, put the same URL behind npx mcp-remote https://api.billos.co.il/mcp --header "X-Api-Key: bk_live_...".

The tools

Tool	What it does
`list_businesses`	The businesses this key can act on. Call it first: every other tool takes a `businessId` from here
`create_document`	Creates and issues a קבלה / חשבונית מס / חשבונית מס-קבלה, and returns the number plus a public PDF link for the customer
`list_documents`	Issued documents (or drafts), newest first, filterable by date
`cancel_document`	Issues the credit note (זיכוי) that corrects an issued document: the only lawful undo. Both stay in the books
`find_or_create_customer`	Matches a customer by phone then name, creating one only if nothing matches: what stops a second card being opened for a customer of years
`list_customers`	The business's customers
`record_expense`	Records an expense in the ledger. On a pending account it lands as a draft and the result says so, rather than failing
`list_expenses`	Recorded expenses (or drafts), newest first
`financial_summary`	Income, expenses, profit and the VAT position for a date range: the numbers behind "how much did I make this month"

Nine verbs, not forty endpoints: a model composes far better from a small set of complete business actions than from a mirror of the REST surface. Anything the tools don't cover is still one REST call away.

> Issuing and correcting arrived together on purpose. An agent that can create a permanent tax document but cannot correct one is the wrong asymmetry to hand a model: it makes the dangerous half easy and the repair impossible. cancel_document is the counterpart, and it is a real credit note: nothing is deleted, both documents stay in the books, which is exactly what the law requires.

What an agent can and cannot do

Everything in this document still applies: the MCP endpoint is another door to the same wall, not a way around it:

Money is agorot here too. priceIncVatAgorot: 35400 is ₪354.00. One unit convention across every surface beats a friendlier one that silently differs.
Issuing is permanent. create_document allocates a legal sequential number and signs a PDF; the tool description tells the model to confirm with the user first, and you should keep that instruction in any wrapper you build.
The same gates fire. Account approval, per-business monthly ceilings, deactivation, rate limits, scopes: an agent meets them exactly as curl does, with the same reason codes.
A business your key doesn't own is invisible. The tool answers "business not found under this credential", never a hint that the id exists.
Nothing streams and nothing is stored. The server keeps no session: each call is a stateless, authenticated POST.

> Give an agent a bk_test_ key first. The sandbox is a real second database (section 10) where nothing is signed, nothing reaches the tax authority, and every mistake is free: the right place to discover how your prompts behave before a model issues a real invoice.