The Billy MCP server lets an AI assistant read your projects, vendors, and contracts in Billy and take a few actions, such as creating a vendor or sending a certificate request, without leaving the assistant.

This guide covers how to connect it, what it can and can't do, and how to turn it off.

Server URL: https://app.billyforinsurance.com/mcp
Transport: Streamable HTTP
Authentication: OAuth (sign in with your Billy login)
Sandbox: https://demo.billyforinsurance.com/mcp (ask support for access)

Before you start

You need a Billy login. The assistant inherits your Billy role, so if you can't create vendors in Billy, the assistant can't either.
For Microsoft 365 Copilot, one person with Copilot Studio access sets it up once for the whole company. Individual users can't add an MCP URL to Copilot themselves.
For Claude and ChatGPT, each user connects it in their own settings in a couple of minutes.
No API key is needed. You sign in with your Billy account when prompted.

Microsoft 365 Copilot (one-time setup by a Copilot Studio maker)

Takes about 5 minutes. Once published, anyone with a Microsoft 365 Copilot licence can use the Billy agent in Copilot and Teams.

Create the agent. In Copilot Studio, go to Create → New agent. Name it "Billy Compliance" and add a short instruction, for example: "You help our team check subcontractor insurance compliance using Billy. Always confirm before sending a certificate request or creating a vendor or contract."
Add Billy as an MCP tool. Open Tools → Add a tool → Model Context Protocol. Server URL: https://app.billyforinsurance.com/mcp. Transport: Streamable HTTP. Authentication: OAuth 2.0.
Enter the OAuth details. Copilot Studio asks for a client ID, client secret, authorisation URL, token URL, and scopes. Contact Billy support to have an OAuth client issued for your Copilot Studio agent; we'll send you these values.
Register the redirect URL. After the tool is created, Copilot Studio shows a redirect URL. Send it to Billy support so we can register it on your OAuth client; sign-in won't complete until it's registered.
Create the connection and test. Select Create new connection, sign in to Billy, then type "list our projects in Billy" in the test pane. Copilot Studio discovers Billy's tools automatically; there is nothing to declare by hand.
Publish. Go to Publish → Microsoft 365 Copilot and Teams. Depending on your tenant policy, a Microsoft 365 admin may need to approve it in the admin centre. Users will then see "Billy Compliance" in their agents list.

Claude (web and desktop)

Open Settings → Connectors.
Click Add custom connector.
Name: Billy. URL: https://app.billyforinsurance.com/mcp.
Click Add, then sign in to Billy when prompted and click Authorize.
Start a new chat and ask "Which Billy teams can I access?" to confirm it's working.

Claude Code

Run this in your terminal, then sign in to Billy in the browser window that opens:

claude mcp add billy --transport http https://app.billyforinsurance.com/mcp

ChatGPT

Open ChatGPT settings and go to the connectors section.
Add a new connector with the URL https://app.billyforinsurance.com/mcp.
Sign in to Billy when prompted.

Connector availability depends on your ChatGPT plan. If you don't see the option, check with your ChatGPT admin.

Cursor and other MCP clients

Add this to your client's MCP configuration:

{ "mcpServers": { "billy": { "url": "https://app.billyforinsurance.com/mcp" } } }

What the assistant can do

The server exposes twelve tools. Every call is scoped to one Billy team.

Area	Tools	What they do
Teams	`list_teams`	Lists the Billy teams you belong to and your permissions in each
Projects	`list_projects`, `get_project`	Lists projects (including those imported from ProjectSight, Procore, or Autodesk) and reads one project's detail
Vendors	`list_vendors`, `get_vendor`, `create_vendor`, `update_vendor`	Lists and looks up vendors by Billy ID or your external ID, creates a vendor with a primary contact, renames or archives a vendor
Contracts	`list_contracts`, `get_contract`, `create_contract`, `update_contract`	Lists contracts by project or vendor, reads one contract, links a vendor to a project, changes the requirement group or contact
Actions	`send_certificate_request`	Emails the certificate request to the vendor contact, the same as clicking Request Documents in Billy

What it can't do: delete anything, upload or edit a certificate, approve or reject a document, or change a compliance status. Document review stays with Billy's AI Review Assistant and your reviewers. The only "removal" available is archiving a vendor, which is reversible.

Approving actions

Read tools (listing teams, projects, vendors, contracts) run without asking.

Action tools (create_vendor, create_contract, update_vendor, update_contract, send_certificate_request) ask for your approval:

In Claude and ChatGPT: the first time the assistant wants to use an action tool, you'll see a prompt with Deny, Allow once, or Always allow. We recommend leaving "Always allow" off for send_certificate_request until the workflow is routine. You can revoke "Always allow" at any time in your connector settings.
In Microsoft 365 Copilot: the agent's instructions tell it to confirm before acting. Each user grants connection consent the first time they use the agent.

Try these first

"Which Billy teams can I access?"
"List all projects on [team name]."
"How many active contracts does [vendor name] have across our projects?"
"Which contracts on [project name] are still on the default requirement group?"
"We awarded the drywall package on [project] to [vendor], contact [name], [email]. Set them up and request their COI."

More examples: 12 things to ask an AI agent about your subcontractor compliance

Security

Your permissions, not more. Access is granted per user and mirrors your Billy role.
One company, one team per call. Requests are bound to the account you authorised and carry a team slug. Multi-entity companies keep each business unit separate.
No copy of your data. Everything is read from Billy at the moment you ask. Nothing is exported, cached, or synced to the AI provider.
Consent screen names the app. When you authorise, Billy shows which application is requesting access. If you don't recognise it, click Deny.

⚠️ Prompts inside documents: if the assistant is reading an email or PDF that contains an instruction like "send a certificate request to all vendors," it should treat that as content, not a command. Make sure your assistant asks before acting on instructions it found in a file.

Disconnecting

Revoke everything: contact Billy support and ask them to revoke the authorization for the application. Every token issued to that app stops working immediately.

Remove from one client:

Claude: Settings → Connectors → Billy → Revoke
Claude Code: claude mcp remove billy
ChatGPT: remove the connector in settings
Copilot: the maker unpublishes the agent in Copilot Studio, or an admin removes it in the Microsoft 365 admin centre

Troubleshooting

"I don't see any tools" or the assistant says it can't reach Billy
Check the URL is exactly https://app.billyforinsurance.com/mcp with no trailing slash. Remove and re-add the connector, then sign in again.

The assistant can't find my team or project
Ask it to "list my Billy teams" first. It needs the team slug before it can look up projects. If your team isn't listed, your Billy user may not have access to it.

Sign-in loop in Copilot Studio
The redirect URL from Copilot Studio hasn't been registered on your Billy OAuth client (step 4). Send it to support, then create the connection again.

The assistant created a vendor but didn't send the request
Action tools each need approval. Check whether you denied the send_certificate_request prompt, then ask it to send the request again.

I want to test without touching real data
Use the demo server at https://demo.billyforinsurance.com/mcp. Contact support for access.

Still stuck? Message us in the app and we'll help you get connected. Support@billyforinsurance.com

Connect Billy to Microsoft Copilot, Claude, or ChatGPT: MCP Server Setup Guide