Bill MCP server
Bill is billing and bookkeeping software for South African attorneys, advocates and their practices. Its MCP server lets an AI assistant read a practice’s clients, matters, time, invoices, payments and accounts, and, with the user’s permission, add records as drafts. To connect Claude or ChatGPT as a user, see connecting an AI assistant.
When to use it
- Answer questions about a practice that uses Bill: who owes money, unbilled time on a matter, this month’s fees, a client’s statement, the business and trust ledgers.
- Record work as it happens: add a client or matter, or log a draft time entry or expense for the user to approve in Bill.
- Not for approving, invoicing, sending or paying. Those stay in Bill, and the server has no tools for them.
Endpoint
- URL
https://mcp.bill.co.za/mcp- Transport
- Streamable HTTP, stateless. Each
POSTis one JSON-RPC exchange answered with a JSON body. There is no SSE stream, no session, and no batching. - Rate limit
- Per connection. A client over the limit gets a
429and should wait before retrying.
Sign-in
OAuth 2.1 authorisation code flow with PKCE (S256). An unauthenticated request gets a 401 whose WWW-Authenticate header points at the protected resource metadata.
- Protected resource metadata (RFC 9728):
https://mcp.bill.co.za/.well-known/oauth-protected-resource/mcp - Authorisation server metadata (RFC 8414):
https://mcp.bill.co.za/.well-known/oauth-authorization-server
Clients register with a Client ID Metadata Document. There’s no dynamic client registration, and only Claude and ChatGPT are accepted.
bill:read- Read the practice the user picks when they connect: the same information they can see in Bill.
bill:write- Add clients and matters, and draft time entries and expenses. The user opts in on the consent screen.
offline_access- A refresh token, so the connection lasts beyond one session. The user can disconnect it at any time from Bill’s settings.
Tools
The server lists its tools after sign-in. Every tool has a title and read-only, destructive and open-world hints, and the server sends instructions explaining Bill’s vocabulary when a client connects.
- Tool names use Bill’s internal words: a matter is a client project, a time entry is a client project activity, and an expense is a supplier invoice.
- Money fields ending in
MinorUnitshold cents, and each has aFormattedsibling such as R1,500.00. - Lists are paged. Continue with the
cursorfromnextCursorrather than raisinglimit. - A write tool takes an optional
dryRunargument that returns a preview without saving. An identical write repeated within a few minutes usually returns the first result rather than saving a duplicate.
REST API
Bill has no public REST API. The MCP server is the supported way for software outside Bill to read and add records.