Bilio MCP connector: setup, scopes and tools

Connector URL

https://mcp.getbilio.com/mcp

Transport: Streamable HTTP. Authentication: OAuth 2.1 with your Bilio account. You do not need an API key.

Set it up

Claude: Settings → Connectors → Add custom connector. Paste the URL, then click Connect and sign in to Bilio.
ChatGPT: Settings → Apps & Connectors → Create (developer mode). Paste the URL as the MCP server, choose OAuth, then sign in to Bilio.
Cursor: Settings → MCP → Add new MCP server, or add this to your mcp.json. Cursor opens Bilio to sign in.
{ "mcpServers": { "bilio": { "url": "https://mcp.getbilio.com/mcp" } } }

Menu names change often in assistant apps. If yours look different, look for “custom connector” or “MCP server” and paste the URL above.

When you sign in, Bilio shows a consent screen. Pick the company the assistant may use and switch on what it may do. One connection works in one company. Change permissions or disconnect any time in Settings → Connected assistants, where you also see when each assistant was last used and what it recently created.

Scopes and plans

Scope	Allows	Availability
`bilio.read`	Read clients, invoices, quotes, expenses and reports.	Every plan, including Starter
`bilio.write`	Create, change, delete and send, within the permissions you give each assistant.	Pro and Business (and their 14-day trial)

Permissions per assistant

Permission	Allows	Default
Read	Clients, invoices, quotes, expenses and reports. Always on.	Always on
Create and edit drafts	Draft invoices and quotes, clients and expenses. Drafts never reach a client.	On
Change status	Mark invoices paid, due or unpaid, or revert one to draft. No email is sent.	Off
Delete	Remove draft invoices and quotes, clients with no invoices, and expenses. Always shows a preview and asks you to confirm.	Off
Send emails to clients	Invoices, quotes and payment reminders, with the PDF attached. Always shows you a preview and asks you to confirm before it goes out.	Off

Writing also needs an owner or admin role: viewers can only ever read. Permission changes apply to the next request, with no need to reconnect.

Tools

11 read tools, plus tools to draft, change status, delete and send. All work in the company you chose when you connected. Amounts come with their currency, and dates are ISO dates (YYYY-MM-DD).

Read

Tool	What it does
`whoami`Connected company	Which company this connection works in, your role and plan, and what this connection may do.
`list_clients`List clients	Clients, optionally filtered by name or email.
`get_client`Get a client	One client with contact details, VAT number and their latest invoices.
`list_invoices`List invoices	Invoices, newest first. Filter by status (draft, sent, paid, overdue), client or invoice date.
`get_invoice`Get an invoice	One invoice with its lines, VAT and payment details.
`list_quotes`List quotes	Quotes, newest first. Status: draft, sent, approved, rejected or expired.
`list_expenses`List expenses	Expenses, newest first. Filter by date, category or vendor.
`get_overdue`Overdue invoices	Sent invoices past their due date, most overdue first, with how many days late.
`get_vat_summary`VAT summary	VAT for a quarter as on the VAT return: VAT charged, VAT on deductible expenses, and the balance to pay or reclaim.
`get_pnl`Profit and loss	Revenue, deductible expenses and the result, excluding VAT, for a year or a date range.
`get_cashflow`Cash flow	Money in and money out, plus what is outstanding and overdue today. Defaults to the current month.

Create and edit drafts

Tool	What it does
`create_client`Create a client	Adds a client. Refuses if a client with the same email exists.
`update_client`Edit a client	Changes a client’s details. Existing invoices keep the details they were made with.
`create_invoice_draft`Draft an invoice	A draft invoice with your next number, default VAT rate, currency, bank account and the client’s usual payment term. Nothing is sent.
`update_invoice_draft`Edit a draft invoice	Replaces a draft’s lines, dates, currency or notes. Only drafts can be edited.
`duplicate_invoice`Duplicate an invoice	A draft copy of an invoice with a new number and today’s date, like Duplicate in the app.
`create_quote_draft`Draft a quote	A draft quote with a valid-until date (30 days by default). Nothing is sent.
`update_quote_draft`Edit a draft quote	Replaces a draft quote’s lines, currency, valid-until date or notes.
`create_expense`Log an expense	Adds an expense, amount including VAT, in one of Bilio’s categories.
`update_expense`Edit an expense	Changes an expense’s date, vendor, amount, VAT, category or whether it is deductible.
`categorise_expense`Change an expense category	Sets the category of an expense.

Change status

Tool	What it does
`mark_invoice_paid`Mark an invoice as paid	Records payment of a due or overdue invoice, like “Mark as Paid”. No email is sent.
`mark_invoice_sent`Move an invoice to Due	For invoices you sent yourself outside Bilio, like “Move to Due”. Does not email the client.
`mark_invoice_unpaid`Undo “paid”	Moves a paid invoice back to Due and removes the payment record, to correct a mistake.
`revert_invoice_to_draft`Revert an invoice to draft	Moves a due invoice back to draft so it can be edited. Anything already emailed stays with the client.

Delete

Tool	What it does
`delete_invoice_draft`Delete a draft invoice	Draft invoices only: due and paid invoices are part of your books and can’t be deleted.
`delete_quote_draft`Delete a draft quote	Draft quotes only.
`delete_client`Delete a client	Only clients with no invoices or quotes.
`delete_expense`Delete an expense	Any expense.

Send emails to clients

Tool	What it does
`send_invoice`Send an invoice by email	Emails an invoice with its PDF attached, exactly like Send in Bilio; a draft becomes Due.
`send_quote`Send a quote by email	Emails a quote with its PDF attached, like Send in Bilio.
`send_reminder`Send a payment reminder	Emails a reminder for a due or overdue invoice, with the invoice PDF attached.

Safety rules

Everything an assistant creates is a draft. Drafts never reach a client.
Sent and paid invoices can’t be edited or deleted: they are part of your books. Revert to draft or undo “paid” first, with the status permission.
Deletes take two steps. The first call returns a preview and a one-time code; only a second call with that code deletes. The code works once, for that record and that connection, and expires after 10 minutes.
Changing status never emails your client.
Emails to clients (invoices, quotes and reminders) take two steps as well: a preview first, and nothing is sent until you confirm. Sending needs the send permission, which is off by default.

For developers: OAuth details

Authorization server metadata: mcp.getbilio.com/.well-known/oauth-authorization-server
Protected resource metadata: mcp.getbilio.com/.well-known/oauth-protected-resource/mcp
Authorization code flow with PKCE (S256), dynamic client registration, client ID metadata documents and token revocation.
Tokens are bound to https://mcp.getbilio.com/mcp. Access tokens last 1 hour; refresh tokens 30 days.
Unauthenticated requests get 401 with a WWW-Authenticate header that points to the resource metadata.

Where your data goes

The connector runs in the EU (europe-west1 (Belgium)), next to the Bilio database. What a tool returns goes to the assistant you connected, and that provider’s own terms apply to it. The privacy policy has the details.

Help

Something not working, or a tool you need? Email [email protected]. For what the connector is for and what to ask, see Natively AI.