Connecting an AI assistant
The server URL, the setup steps for Claude, ChatGPT and Codex, what an assistant can do, and how connections expire.
Connecting an AI assistant is in alpha and available to selected workspaces only. Existing users can get in touch with us to have it enabled for their workspace.
Billow has an MCP server. MCP (Model Context Protocol) is how assistants such as Claude, ChatGPT and Codex talk to other tools. An assistant connected to Billow can look up open invoices, draft an invoice, or add a lead from a chat.
The MCP page
Connections are managed under Settings → MCP. The page is visible to owners and admins, and only while AI assistant access is switched on for the workspace.
The server URL
Every assistant is pointed at the same address:
The URL is the same for every workspace. Which workspace an assistant reaches is decided when you authorize it, not by the URL.
What an assistant can do
An assistant acts as you, inside one workspace. It sees what your role lets you see.
Accounts | Contacts | Leads | Projects | Offers | Invoices | |
|---|---|---|---|---|---|---|
Read | Yes | Yes | Yes | Yes | Via project | Yes |
Create | Yes | Yes | Yes | Yes | Via project | Draft only |
Update | Yes | Yes | Yes | Yes | Draft only | Draft only |
Invoices created by an assistant are drafts. They carry no number and stay fully editable until you send them from Billow. Deposit invoices can’t be created this way. When the project has an offer, currency and tax rates and labels follow that offer. A value the assistant sends that differs from the offer is refused.
Offers can’t be created on their own. Creating one means creating a project with an offer.
Before creating an account or a contact, the assistant checks for an existing record with the same name. When it finds one, it stops and asks you whether the two are the same before creating another.
Anything an assistant changes shows up in the activity feed with the assistant’s name, so you can always tell what it did.
Creating a project
When you ask for a project, the assistant checks which kind you want: a simple project without an offer, which starts Active, or a project with an offer, which starts as a Draft.
With an offer, the assistant can fill in the essentials step, offer date and Offer Valid Until, and the deliverables step: each deliverable’s title, description, price, quantity, upsell flag and timeline, the deposit percentage, the tax rate and, with advanced tax mode on, a second tax rate, the offer note, and currency. The contract and review steps stay in Billow, since signing happens there. See Building and sending an offer.
Creating a project through an assistant counts toward the plan’s active-project limit the same as creating one in Billow, and is refused with the same message once the limit is reached. See Projects and their statuses.
Editing a project or offer
An assistant can update a project’s name, account, main contact and summary. The account only changes while nothing has locked it, the same rule as editing a project yourself.
While an offer stays Draft, an assistant can also update the offer date, Offer Valid Until, and the deliverables step: deliverables, deposit percentage, tax rate, offer note and currency.
A simple project stays editable by an assistant at any status. A project with an offer is only editable by an assistant while its offer is Draft.
If you’ve already signed the contract on a Draft offer, any assistant edit to the project or the offer, including renaming the project, is refused unless the assistant explicitly confirms the edit should invalidate the contract, the same confirmation Billow asks for when you edit a signed contract yourself. The contract then has to be signed again. See Contracts and signatures.
Editing an invoice
An assistant can only edit an invoice while it is Draft. A Pending, Paid or Refunded invoice refuses the edit. Sending an invoice, marking it paid and refunding it stay in Billow.
On a Draft invoice, an assistant can update the account, project, contact, title, invoice date, due date, note, payment method and bank account, currency, and both tax lines. Sending line items replaces the invoice’s full list; leaving them out keeps the existing ones. See Creating and sending an invoice.
A deposit invoice still lets an assistant update its header fields: title, contact, dates, note, payment method and bank account. Its project, account and line items stay locked, and an attempt to change any of the three is refused with an explanation. A deposit invoice’s line items are a snapshot of the accepted offer.
When the invoice’s project has an offer, currency and the tax rates and labels follow that offer. A value the assistant sends that differs from the offer is refused. Leaving a value out fills it from the offer.
An edit that changes nothing leaves no entry in the activity feed. An edit that changes something appears there with the assistant’s name, like any other assistant write.
An assistant never:
Sends, signs, accepts, marks an invoice paid, or refunds anything
Changes a project’s status directly
Converts a lead into a project
Attaches an offer to an existing simple project
Claude
Open Settings → Connectors.
Click Add custom connector.
Name it Billow and paste the server URL.
Click Add, then Connect and sign in to Billow.
Claude Code
Run this in a terminal:
In a session, run /mcp and follow the sign-in link.
ChatGPT
Open Settings → Plugins, then Add → Add MCP server.
Name it Billow and set Type to Streamable HTTP.
Paste the server URL. Leave the token and header fields empty.
Save, then sign in to Billow when prompted.
Codex
Run these two commands:
The second command opens the sign-in. In a session, /mcp lists Billow as connected.
Authorizing
Signing in from an assistant opens a Billow page titled Connect, followed by the assistant’s name.
The page lists every workspace where you are an owner or admin and AI assistant access is switched on. Pick one. The connection is bound to that workspace and can’t reach any other. To use an assistant with a second workspace, connect it again and pick the other workspace.
Connect Claude
Claude will be able to read your accounts, projects, offers and invoices, and to create accounts, leads, projects, offers and draft invoices. It acts as you, in one workspace only.
Your connections
Each connection appears as a card on the MCP page, showing the assistant’s name, whether it is enabled or expired, and when it was last used. Connections are personal: you see your own, and other members see theirs.
Status | Meaning |
|---|---|
enabled | The assistant can reach the workspace |
expired | The assistant has to sign in again before it can be used |
A connection expires after 90 days without use.
Disconnecting
Disconnect on a connection card cuts the assistant off immediately. The assistant keeps its entry for Billow, so to reconnect later you sign in from the assistant again.
Reconnect on an expired card removes the old connection. Sign in again from the assistant to create a new one.
Access follows your role
Connections belong to the person who made them and depend on that person’s role.
A member who leaves the workspace loses every connection to it.
A role that drops from admin to Member removes that person’s connections.
Subscription limits apply to assistants the same way they apply in Billow. A workspace in read-only mode can be read by an assistant but not changed.
