Connecting an AI assistant
How to connect Claude, Claude Code, ChatGPT or Codex to your workspace, what a connected assistant can and cannot change, and how to disconnect or reconnect it.
You can connect an AI assistant such as Claude, ChatGPT or Codex to your workspace through Billow’s MCP server. MCP (Model Context Protocol) is how assistants talk to other tools. A connected assistant can look up open invoices, draft an invoice or add a lead from a chat. Only owners and admins can connect an assistant.
Copy the server URL
Go to Settings → MCP.
Click the address under Server URL to copy it.
Every assistant uses the same address:
The URL is the same for every workspace. The workspace an assistant reaches is the one you choose when you authorize it.
The MCP tab only appears for owners and admins.
Connect Claude
In Claude, open Settings → Connectors.
Click Add custom connector.
Name it Billow and paste the server URL.
Click Add, then Connect.
Sign in to Billow and authorize the connection.
Connect Claude Code
Run this command in a terminal:
Then finish the connection:
In a Claude Code session, run
/mcpand follow the sign-in link.Sign in to Billow and authorize the connection.
Connect ChatGPT
In ChatGPT, open Settings → Plugins, then choose 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.
When prompted, sign in to Billow and authorize the connection.
Connect Codex
Run these two commands in a terminal:
The second command opens the Billow sign-in page. Sign in and authorize the connection.
In a Codex session, /mcp lists Billow as connected.
Authorize the connection
Signing in from an assistant opens a Billow page titled Connect, followed by the assistant’s name.
If you are an owner or admin of more than one workspace, choose one under Workspace. If you are an owner or admin of only one, the page names it instead.
Click Authorize.
The page describes what the assistant gets:
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.
The connection is bound to the workspace you chose and cannot reach any other. Each assistant connects to one workspace at a time. If you authorize it again and choose a different workspace, the connection moves there and replaces the old one. Cancel sends you back to the assistant without connecting.
If you are not an owner or admin of any workspace, the page says “None of your workspaces can be connected to an AI assistant. Access is limited to workspace owners and admins.”
What an assistant can do
An assistant acts as you, inside one workspace, and sees what your role lets you see.
Accounts | Contacts | Leads | Projects | Offers | Invoices | |
|---|---|---|---|---|---|---|
Read | Yes | Yes | Yes | Yes | Through the project | Yes |
Create | Yes | Yes | Yes | Yes | Through the project | Drafts only |
Update | Yes | Yes | Yes | Yes | Drafts only | Drafts only |
An assistant follows the same rules you do: it can only edit offers and invoices while they are drafts, it can’t change what an accepted offer locked, and projects it creates count toward your plan’s active-project limit.
What an assistant cannot do
An assistant never:
Sends, signs or accepts anything
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
Creates a deposit invoice
Creates an offer on its own
Use Imports for past invoices
An invoice an assistant creates is a new Billow draft: it gets Billow’s INV- numbering when sent and is not marked Paid. To bring in invoices you already issued in another tool, use Settings → Imports, as described in Importing past invoices. Imported invoices are recorded as Paid, so import only invoices your clients have already paid.
Your connections
Each connection appears as a card under Settings → MCP. The card shows the assistant’s name, its status, and when it was last used, or when it was connected if it hasn’t been used yet. Connections are personal: you see your own, and other owners and admins see theirs.
Status | What it means |
|---|---|
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.
Disconnect an assistant
Go to Settings → MCP.
Click Disconnect on the assistant’s card.
Click Disconnect in the dialog.
The assistant loses access to the workspace immediately. It keeps its entry for Billow, so to connect it again later, sign in from the assistant.
Reconnect an expired assistant
Go to Settings → MCP.
Click Reconnect on the expired card.
Click Reconnect in the dialog. Billow removes the expired connection.
In the assistant, add Billow again with the server URL, then sign in and authorize the connection.
Access follows your role
Connections belong to the person who made them and depend on that person’s role.
If you leave the workspace or are removed from it, all your connections to it are removed.
If your role changes from owner or admin to Member, your connections are removed.
If the workspace is deleted, every connection to it is removed.
Once a connection is removed, the assistant’s next request is refused with “This assistant is no longer connected to Billow. Reconnect it from your assistant to keep using it.”
Plans and subscriptions
Your plan and subscription apply to an assistant the same way they apply in Billow.
If the workspace becomes read-only because its subscription has lapsed, an assistant can still read it but cannot change anything. It is refused with “Your subscription has lapsed. Resubscribe to make changes.” See Failed payments, cancelling and read-only access.
You can still disconnect an assistant while the workspace is read-only.
If the workspace has no subscription at all, an assistant is refused with “This workspace has no Billow subscription. Choose a plan in Billow to continue.”
If your plan does not include the lead pipeline, an assistant cannot create or update leads. See Plans and limits.
