# MCP: BillOS for AI agents

**One line of config puts BillOS inside Claude, Cursor, or anything else that speaks [MCP](https://modelcontextprotocol.io).** 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.

```json
{
  "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.