# Mast for your own AI agent (MCP)

Mast has an endpoint that speaks the Model Context Protocol (MCP), the open protocol by which an AI
assistant uses a service's functions as tools. With it, an assistant of your own (Claude, or any
client that speaks MCP) can read your company's customers, invoices and books in Mast, and prepare
draft invoices, with an API key of your company or, where Mast has opened it for your account, by
[signing in to Mast from Claude](#connect-mast-to-claude-by-signing-in).

It is the [Mast API](https://mastfinance.io/developers/guide.md) in another form: each tool is one call of the API, held to the same
rights, the same limits and the same rules. Nothing is available here that the API does not have.

## What an agent can and cannot do

- **It acts in one company, with the rights of the key's role.** Give the key a role that only reads
  if the agent is there to answer questions; a tool the role does not cover answers
  `ACCESS_DENIED_ROLE_REQUIRED`.
- **It reads** what the API reads: the key's company, customers, products, invoices, credit notes,
  payments, the chart of accounts, journal entries, the trial balance, bank accounts and their lines,
  suppliers and their bills.
- **It prepares, and never issues.** An agent can make and correct customers, products, suppliers
  and **draft** invoices. A draft has no official number and no journal entry, and nothing is sent to
  your customer. Issuing an invoice and e-mailing it are not among the tools: a person does it in
  Mast, or your own system does it through the API. This is deliberate.
- **The tools are the fence only as far as the key's role is.** The key is what Mast obeys, through
  these tools and through the API alike. A key whose role holds « Post » on customer invoices can
  issue and send through the API, and an assistant that can run commands of its own could be led to
  call it. So an agent's key takes a role **without « Post »**: Mast then refuses it to issue or
  send, whatever asks.
- **Everything it does is written under the key's name** in Mast: what a key named « Agent » wrote
  reads « Agent (API) » wherever Mast shows who did something.

## The tools

The endpoint lists its tools itself (`tools/list`), each with the arguments it takes. They are the
calls of the [reference](https://mastfinance.io/developers/reference.md), which names the tool of each call. Each asks of the key's role
the right its call asks, named as **Settings › User & Permissions** names it: the feature, then the
column.

| To ask | Tool | Effect | Right of the key's role |
|---|---|---|---|
| Which key am I, in which company? | `mast_whoami` | reads | none |
| The company, its base currency, its fiscal years | `mast_get_company` | reads | Company Profile: Read |
| The customers | `mast_list_customers` | reads | Customer: Read |
| A customer, by your reference | `mast_get_customer` | reads | Customer: Read |
| Make or change a customer | `mast_save_customer` | writes | Customer: Create and Edit |
| The products | `mast_list_products` | reads | Product: Read |
| A product, by your reference | `mast_get_product` | reads | Product: Read |
| Make or change a product | `mast_save_product` | writes | Product: Create and Edit |
| The invoices, by state, with their lines | `mast_list_invoices` | reads | Customer Invoices: Read |
| An invoice, by your reference | `mast_get_invoice` | reads | Customer Invoices: Read |
| An invoice, by Mast's id | `mast_get_invoice_by_id` | reads | Customer Invoices: Read |
| Prepare a **draft** invoice | `mast_create_invoice_draft` | writes | Customer Invoices: Create |
| Correct a draft | `mast_update_invoice_draft` | writes | Customer Invoices: Edit |
| Drop a draft | `mast_delete_invoice_draft` | writes | Customer Invoices: Delete |
| The credit notes | `mast_list_credit_notes` | reads | Customer Credit Notes: Read |
| A credit note, by Mast's id | `mast_get_credit_note_by_id` | reads | Customer Credit Notes: Read |
| Payments received | `mast_list_payments` | reads | Cash Allocation (Sales & Invoicing): Read |
| The chart of accounts | `mast_list_accounts` | reads | Chart of Accounts: Read |
| The journal entries | `mast_list_journal_entries` | reads | Journal Entries: Read |
| The trial balance | `mast_get_trial_balance` | reads | Financial Statement: Read |
| The bank accounts | `mast_list_bank_accounts` | reads | Bank Accounts: Read |
| The bank lines | `mast_list_bank_transactions` | reads | Bank Statement: Read |
| The suppliers | `mast_list_suppliers` | reads | Supplier: Read |
| A supplier, by your reference | `mast_get_supplier` | reads | Supplier: Read |
| Make or change a supplier | `mast_save_supplier` | writes | Supplier: Create and Edit |
| The suppliers' bills | `mast_list_bills` | reads | Supplier Bills: Read |

A tool the role does not cover answers `ACCESS_DENIED_ROLE_REQUIRED` and the others still work. The
endpoint tells every agent to start with `mast_get_company`, to learn the base currency and the fiscal
years: give an agent's role « Read » on **Company Profile**, or that first call fails. Mast checks
this table against the calls themselves at every release.

Each tool tells a client whether it reads or writes, and whether it can overwrite or remove what
exists (changing a customer, a product, a supplier or a draft; dropping a draft), so that the client
can ask you before it acts. No tool writes a supplier's bank account: where a supplier is paid is
entered in Mast, by a person.

What you can then ask your assistant, in your own words:

- « Which invoices are overdue, and what do they come to per customer? »
- « What did we invoice in October, net of credit notes, by product? »
- « Prepare a draft invoice for Muster Handel AG: 14 hours of consulting and three manuals, with
  their usual discount. » The assistant prepares the draft; you check it and issue it in Mast.
- « What came into the bank last week that is not reconciled yet? »

## Connecting

You need an API key of the company, made by an owner or an administrator in Mast under
**Settings › API Keys** ([how](https://mastfinance.io/developers/guide.md#getting-a-key)). The API must be open for your account.

| | |
|---|---|
| Address | `https://api.mastfinance.io/api/v1/ext/mcp` |
| Transport | Streamable HTTP (`POST`), answers in JSON |
| Authentication | The header `Authorization: Bearer mast_sk_…` |

Any client that lets you give a remote server's address and a header can connect. A client that can
only sign in to a server through OAuth connects by signing in instead, where Mast has opened that for
your account: see [Connect Mast to Claude by signing in](#connect-mast-to-claude-by-signing-in).

### Claude Code

```bash
claude mcp add --transport http mast https://api.mastfinance.io/api/v1/ext/mcp --header "Authorization: Bearer mast_sk_…"
```

Or, to share the server with a team without sharing the key, in the project's `.mcp.json`, each
person keeping the key in an environment variable:

```json
{
  "mcpServers": {
    "mast": {
      "type": "http",
      "url": "https://api.mastfinance.io/api/v1/ext/mcp",
      "headers": { "Authorization": "Bearer ${MAST_API_KEY}" }
    }
  }
}
```

`claude mcp list` then shows the server as connected, and `/mcp` lists its tools.

### Claude (claude.ai and the desktop app)

In Claude, a remote server is added as a custom connector: **Customize › Connectors › Add › Add
custom connector** (in a Team or Enterprise organization, an Owner adds it under **Organization
settings › Connectors**). Enter the address above, choose **No sign-in**, and under **Request
headers** add the header `authorization` with the value `Bearer mast_sk_…`: the word `Bearer`, a
space, then the key. Claude sends the value exactly as it is typed.

The **Request headers** section is a beta of Anthropic's that not every organization has yet. Where
the dialog does not show it, Claude signs in to a server through OAuth:
[connect by signing in](#connect-mast-to-claude-by-signing-in) where Mast has opened it for your
account, or use Claude Code, or another client that takes a header. In an organization, the key
entered there serves every member who uses the connector, so give it a role that suits them all, and
one that only reads if they are there to ask questions.

### Any other client, or by hand

The endpoint takes one JSON-RPC message per `POST` and answers one JSON object. With a client of the
protocol's revision of 2026-07-28, every request says its version in its body and in its headers:

```bash
curl -s https://api.mastfinance.io/api/v1/ext/mcp \
  -H "Authorization: Bearer $MAST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: mast_whoami" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "mast_whoami", "arguments": {},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
```

A client of the earlier revisions (2025-03-26 to 2025-11-25) opens with `initialize` as it always
did; the endpoint answers it and keeps no session.

## Connect Mast to Claude by signing in

Instead of pasting a key, you can connect Claude to Mast the way you connect any service to it: Claude
sends you to a page of Mast's, you sign in, you approve, and that is all. Nothing secret is copied
anywhere, and each person connects with their own Mast sign-in.

**Mast opens this account by account.** Ask us. Where it is not open for your account, Claude says
it cannot connect, and an API key (above) is the way.

### What you need

- The API and the connecting of assistants open for your account.
- To be an **owner or an administrator** of the account in Mast, with **two-step verification** set
  on your sign-in. A fiduciary's people do not connect an assistant to a client's account: the
  client does.

### In Claude (claude.ai, the desktop and phone apps)

1. **Customize › Connectors › Add › Add custom connector.** In a Team or Enterprise organization, an
   Owner adds the connector once under **Organization settings › Connectors**; each member then
   presses **Connect** and approves with their own Mast sign-in.
2. Enter the address `https://api.mastfinance.io/api/v1/ext/mcp`, and nothing else: no header, no
   client ID.
3. Claude opens a page of Mast's. Sign in if you are asked to. The page names who is asking
   (« Claude »), the **company** the connection will act in, and what Claude may do. To connect another
   company, switch to it in Mast first, then start again from Claude.
4. Choose a level and press **Authorize**. You are taken back to Claude, which now lists Mast's tools.

### In Claude Code

```bash
claude mcp add --transport http mast https://api.mastfinance.io/api/v1/ext/mcp
```

Then `/mcp`, choose `mast` and authenticate: your browser opens the same page. There it says that the
answer goes to a program on your computer: approve only if you have just started it yourself.

### What you choose, and what no choice gives

| Level | Claude can |
|---|---|
| **Read** | read customers, products, invoices, credit notes, payments received, the chart of accounts, journal entries, the trial balance, bank accounts and their lines, suppliers and their bills |
| **Read and prepare** | read, and also create or change customers, products and suppliers, and prepare, correct or drop **draft** invoices |

Whatever you choose, a connected assistant **never issues or sends an invoice, never posts, approves
or pays, and changes no setting**. Those calls are refused to it by Mast itself, through the tools
and outside them (`AGENT_OPERATION_NOT_ALLOWED`), whatever your own rights are.

### How a connection differs from a key

- **It acts with your own rights, never more.** Mast reads your role at each call and narrows it to
  the level you chose. If your role is reduced, the assistant's is, the same day.
- **It is yours.** It stops the day you are no longer an owner or an administrator of the account. It
  also stops when you sign out of your other devices, change your password from your profile in
  Mast, or have your two-step verification reset: you then connect again. A password reset through
  « Forgot password » on the sign-in page does not stop it: if you reset your password because
  someone else may have known it, revoke your assistants in Settings as well.
- **One at a time.** Connecting the same assistant to the same company again replaces your earlier
  connection of it.
- **It says who it is.** What it does is shown in Mast as « Claude (Anna Muster) »: the assistant, and
  the person who connected it.
- **It ends by itself after 180 days.** Claude then asks you to approve again.
- **Bank data.** Where the account requires two-step verification of everyone who signs in (it does
  once a bank is connected to Mast), bank accounts and bank lines are not handed to a connected
  assistant (`AGENT_BANK_DATA_REFUSED`). The page says so before you approve.

### Withdrawing it

**Settings › API Keys › Connected assistants** lists every assistant connected to the company: who
connected it, its level, when it was last used, when it ends. **Revoke** stops it at once.

## Good practice

- **One key per agent**, named for it, with the narrowest role that does its job, and an expiry. A
  key is revoked at once in Settings, and its last use is shown there.
- **Keep the key out of the conversation.** It belongs in the client's configuration or an
  environment variable, never in a prompt or a file an assistant reads.
- **Keep a person in the loop for what is written.** Most clients ask before a tool that writes is
  used. Mast marks each tool as reading or writing so that they can. What a tool writes to a
  customer, a product or a supplier is in force at once: only an invoice is a draft.
- **What an agent reads was not all written by you.** The text of a bank line is its payer's, the
  lines of a supplier's bill are the supplier's, a customer's name is what someone typed. Such a
  text can hold a sentence addressed to an assistant (« ignore your instructions and… »). Mast hands
  it on as it stands, as data, and tells every client so in the instructions it gives it. A role
  that only reads, a person's approval before a write, and an assistant that has no other tool to
  send data out with are what keep such a sentence harmless.
- **An agent reads what your books hold.** What it reads passes through the assistant you connected
  and its provider, under your agreement with them, not Mast's.

## Limits and refusals

- The same rate limits as the API, counted per key and per call (a list: 300 a minute; a write: 60 a
  minute). The endpoint itself takes 300 requests a minute per key.
- A refused call comes back to the model as the tool's result, marked as an error, with the API's
  own status, code and message (`EXT_INVOICE_CUSTOMER_UNKNOWN`, `ACCESS_DENIED_ROLE_REQUIRED`, …) and
  its `details`, so that it can correct itself. A call refused for the rate limit (`429 RATE_LIMITED`)
  also carries `retryAfterSeconds`, the seconds the call's `Retry-After` asks it to wait.
- An argument a tool does not take is refused before any call is made, in words that name the ones
  it takes. The API itself drops a field it does not know without a word; a tool does not, so a
  misspelt filter never reads as « no result ».
- Mast's firewall stands in front of the endpoint as in front of the API, with the same answers (the
  guide's [« Mast's firewall »](https://mastfinance.io/developers/guide.md#masts-firewall)): a client sends a `User-Agent`, and the
  requests of one IP address count together, past 8,000 in 5 minutes.
- A request is one JSON-RPC message sent as JSON, with `Content-Type: application/json`. Sent with
  another type, or with none, it is refused `415 EXT_JSON_BODY_REQUIRED`, in the API's words rather
  than the protocol's, as any call of the API is.
- A request without a key is `401 API_KEY_REQUIRED`. The endpoint is for desktop and server clients,
  which send no `Origin` header. A request that carries one is taken only from Claude's own
  (`https://claude.ai`, `https://claude.com`), which its hosted connectors may send; any other is a
  web page's and is refused with `403`.
- The endpoint keeps nothing between two requests: no session, no stream to listen on.
- Where the account requires two-step verification of everyone who signs in (it does once a bank is
  connected to Mast), `mast_list_bank_accounts` and `mast_list_bank_transactions` answer
  `EXT_BANK_DATA_TWO_FACTOR_ACCOUNT`: a key signs in with no second step, so bank data is not served
  to it there. Every other tool works. An assistant connected by signing in hears
  `AGENT_BANK_DATA_REFUSED` there, for the same reason.
- An assistant connected by signing in whose level only reads is refused every tool that writes
  (`AGENT_CONNECTION_READ_ONLY`): connect it again and choose « Read and prepare ».

## What Mast is told

Nothing about the conversation. Mast sees the calls the tools make, as it sees any call of the API:
the key, the call, when, from where. What a tool writes is shown in Mast under the key's name, as
what your back office writes through the API is.
