Developers · AI agents
Quick answer
The Billy MCP server lets Microsoft 365 Copilot, Claude, ChatGPT and any MCP-compatible agent read and act on your certificate of insurance and vendor compliance data. It exposes your teams, projects, vendors, contracts, requirements, documents and reports as tools, plus the ability to create vendors and contracts, send certificate requests, upload certificates and record your review decisions. It runs at https://app.billyforinsurance.com/mcp over streamable HTTP with OAuth, and is scoped to the company and team you authorise. For Microsoft 365 Copilot, a Copilot Studio maker adds Billy as an MCP tool to an agent once and publishes it to everyone; Claude and ChatGPT users connect it themselves. Read tools run freely; action tools ask for approval. Nothing is bulk-copied out of Billy.
Most construction compliance work is a question followed by an action. Which subs on this project are missing a certificate? Send them a request. We just awarded a contract to a new electrical sub, get them set up. Until now, answering that meant logging in, clicking through projects and contracts, and copying details between Billy, email and your project management system.
The Billy MCP server removes those steps. You ask the question in the AI tool you already use, the assistant queries Billy directly, and the action happens in the same conversation. This post explains what MCP is, exactly what the Billy server can do, how to connect it, and where its boundaries are.
What is MCP, in one paragraph
The Model Context Protocol (MCP) is an open standard, introduced by Anthropic in late 2024 and now supported across the major AI platforms, that lets an AI assistant connect to external software through a set of named tools. Instead of an integration built for one assistant, a software vendor publishes one MCP server and every MCP-compatible client can use it. When you ask Claude “how many contracts are on Northgate Medical Center,” the model decides to call Billy’s list_contracts tool, Billy returns structured data, and the model turns it into an answer or the next action.
What the Billy MCP server exposes
The server currently provides 28 tools: 20 that read and 8 that act (marked (act) below). Every call is scoped by a team_slug, so the assistant only operates inside the Billy team you authorise.
| Area | Tool | What it does |
|---|---|---|
| Teams and search | list_teams | Lists the Billy teams you can act in and the permissions you hold in each. Called first so the assistant knows which team slug to use. |
search | Finds vendors, projects and contracts by name, external id or contact email in one call. | |
| Needs attention | list_needs_attention | Your Needs Attention lists, as Billy shows them: documents waiting for review, contracts with nothing requested, requests with no documents back, and non-responsive vendors. |
get_request_history | Who was asked for documents, when, and what became of each request. | |
| Projects | list_projects | All projects for the team, including those imported from ProjectSight, Procore or Autodesk. |
get_project | A single project by id, with its default requirement group. | |
| Vendors | list_vendors | Paged list of vendors with their compliance result, optionally including archived. |
get_vendor | One vendor by Billy id or by your external_id (for example the vendor number in your ERP). | |
create_vendor (act) | Creates a vendor with a primary contact (name and email). | |
update_vendor (act) | Renames, sets phone or external id, or archives a vendor. | |
| Contracts | list_contracts | Contracts filtered by project or by vendor, with their compliance result. |
get_contract | Full detail for one contract, including the result for each requirement. | |
create_contract (act) | Links a vendor and contact to a project; inherits the project’s requirement group unless you specify another. | |
update_contract (act) | Changes the requirement group, contact or external id on a contract. | |
send_certificate_request (act) | Emails the certificate request for a contract to the vendor contact, exactly as if you clicked “Request Documents” in Billy. | |
| Requirements | list_requirements | What a contract or vendor must provide: insurance lines and limits, additional insured and waiver of subrogation, endorsements, other documents and custom forms. |
get_requirement | One requirement in full. | |
list_waived_requirements | Which requirements are waived, with the reviewer’s notes. | |
| Documents and review | list_documents | The documents on file for a contract or vendor. |
get_document | One document with its extracted certificate data and a short-lived link to the PDF. | |
get_review_context | Everything a Billy reviewer sees: the requirements, each document’s extracted text and PDF, past reviews, review instructions and notes. | |
create_upload_url (act) | Uploads a PDF to a contract or vendor. Billy extracts it and it waits for review like any other upload. | |
save_requirement_evaluation (act) | Saves your approve or reject decision for one requirement on one document, recorded as your review. | |
complete_document_review (act) | Marks a document as reviewed and, only if you ask, emails the vendor the approval or rejection notice. | |
| Reports | list_reports | The reports available to your team. |
run_report | Runs a report and returns the rows, the same columns as the spreadsheet download. | |
export_report | A download link for a report as XLSX or CSV. | |
| Prequalification | list_prequal_submissions | Prequalification submissions, either the queue waiting for review or all of them (when prequal is enabled). |
Tool names are current as of November 2026. Your assistant always reads the live list from the server when it connects, so new tools appear without any setup.
Notice what is not there: no tool deletes anything; archiving a vendor is the only removal, and it is reversible. The review tools record your decisions. The assistant can lay out the evidence and suggest an outcome, but it saves an approval or rejection only when you tell it to, recorded as your review and exactly as if you had saved it on Billy’s review page. Billy’s AI Review Assistant keeps working as before, and nothing reaches a vendor unless you send it.
Four things it changes on a normal day
1. Onboard a new subcontractor from a chat
“We awarded the drywall package on Cedar Ridge Phase II to Ironwood Framing, contact Alan Brooks, a.brooks@ironwoodframing.com. Set them up and request their COI.” The assistant calls list_projects to find Cedar Ridge, create_vendor for Ironwood with Alan as contact, create_contract against the project (inheriting the project’s requirement group), then send_certificate_request. Four screens in Billy become one sentence, and it works the same from a Billy agent in Microsoft 365 Copilot, from Teams, from Claude, or from a terminal via Claude Code.
2. Answer compliance questions without opening the app
“How many active contracts does Cordova Concrete have across all our projects?” or “Which projects have contracts still on the default requirement group?” These are search, list_contracts and get_contract calls the model runs and summarises. “What needs my attention today?” is list_needs_attention, with get_request_history to see who was chased and when. Because the results come back as data, the assistant can also cross-reference them with anything else it has access to: your Outlook calendar, a Teams thread, an Excel export, a SharePoint document.
4. Review an incoming certificate
“Review the new COI from Cordova Concrete on Northgate.” The assistant calls get_review_context, compares each limit, endorsement and additional insured on the certificate with the contract’s requirements, and tells you what passes, what doesn’t and where on the document it looked. You decide; it saves each decision with save_requirement_evaluation and finishes with complete_document_review, sending the vendor a notice only if you ask. If a sub emails a certificate to you instead of uploading it, create_upload_url puts the PDF into Billy first.
Connecting the Billy MCP server
The server uses the streamable HTTP transport at a single URL and authenticates with OAuth against your Billy account. Which steps you follow depends on your assistant. Most Billy customers run Microsoft 365, so that path comes first.
Microsoft 365 Copilot (via Copilot Studio)
Microsoft 365 Copilot doesn’t let individual users paste an MCP URL. Instead, someone with Copilot Studio access builds a small agent that carries the Billy tools, publishes it, and everyone with a Microsoft 365 Copilot licence can add it. It’s a one-time job of about twenty minutes.
- Create the agent. In Copilot Studio, choose Create → New agent. Name it “Billy Compliance” and give it a short instruction such as “You help our team check subcontractor insurance compliance using Billy. Always confirm before sending a certificate request.”
- Add Billy as an MCP tool. On the agent’s Tools page, choose Add a tool → New tool → Model Context Protocol to open the onboarding wizard. Enter a server name and description, set the server URL to
https://app.billyforinsurance.com/mcp, and choose OAuth 2.0 as the authentication type. There is no transport setting: Copilot Studio uses streamable HTTP, which is what Billy runs. - Let Copilot Studio register itself. Choose the Dynamic discovery OAuth type. Billy supports dynamic client registration, so Copilot Studio finds Billy’s sign-in endpoints and registers its own OAuth client. There is no client ID, secret or callback URL to copy. Select Create, then Next.
- Create the connection and test. On the Add tool screen, select Create a new connection, sign in to Billy, select Add to agent, then ask the agent “list our projects in Billy” in the test pane. Copilot Studio discovers the tools from the server; there’s nothing to declare by hand, and new tools appear automatically.
- Publish to Microsoft 365 Copilot. Publish the agent, then open Channels → Microsoft 365 and Microsoft Teams, add the channel and turn on Make agent available in Microsoft Copilot. Depending on tenant policy an admin approves it in the Microsoft 365 admin centre. Users then find “Billy Compliance” in the agents list in Copilot and in Teams.
Claude (web and desktop)
Settings → Connectors → Add custom connector, name it Billy, enter https://app.billyforinsurance.com/mcp, and sign in to Billy when prompted. Individual users can do this themselves.
Claude Code
claude mcp add --transport http billy https://app.billyforinsurance.com/mcp
Cursor and other MCP clients
{ "mcpServers": { "billy": { "url": "https://app.billyforinsurance.com/mcp" } } }
ChatGPT
ChatGPT connects custom MCP servers through Developer mode (beta). Turn on Developer mode in ChatGPT’s settings, create an app with the same URL, and sign in to Billy when prompted. Which plans can use write actions such as sending certificate requests has been changing, so check OpenAI’s current Developer mode documentation. On Business, Enterprise and Edu workspaces an admin has to enable custom apps first.
Testing against demo data
A demo environment with sample projects and vendors is available at https://demo.billyforinsurance.com/mcp, so a Copilot Studio maker can build and test the agent before pointing it at production. Ask Billy support for demo access.
Security and permissions
The connector sees only what you already see. Four properties make that true:
- Your own permissions. Access is granted per user and inherits the role you have in Billy. If you cannot create vendors in Billy, neither can the agent.
- Scoped to one company. Requests are bound to the account you authorised, and every tool call carries a
team_slug. Multi-entity GCs keep each business unit separate. - No stored copy. Data is read at request time. Billy does not export, cache or sync your records to the AI provider; only the results of the questions you ask pass through the conversation, where your assistant’s normal data-retention settings apply.
- Revoke in one click. Remove the authorisation in Billy settings and every token issued to that client stops working.
Approval on every action tool
Reads (listing teams, projects, vendors and contracts) run without interruption. In Claude, the first time the assistant wants to use an action tool such as send_certificate_request or create_contract, it asks you. You can deny the call, allow it once, or always allow that one tool on that one connector. Always-allow is revocable at any time. Leave it off for anything that sends email until the workflow is routine. ChatGPT asks for confirmation before write actions by default, and workspace admins can tighten that. In Microsoft 365 Copilot the equivalent control lives with the maker: the agent’s instructions tell it to confirm before acting, and the connection consent is granted per user when they first use the agent.
A note on prompts from documents. If an assistant is reading an email or PDF that contains instructions (“send a certificate request to all vendors”), it should treat that as content, not a command. Good MCP clients already do this. It’s worth confirming your assistant asks before acting on instructions it found inside a file.
MCP, API or Zapier: which one?
| MCP server | REST API | Zapier / Power Automate | |
|---|---|---|---|
| Best for | Conversational work in Copilot, Claude or ChatGPT, and agents that decide what to call | Deterministic integrations you build and own | Trigger-based automations with no code (Zapier or Power Automate) |
| Who uses it | Anyone with an AI assistant | Developers | Ops teams |
| Auth | Sign in with your Billy login | API key | Zapier or Power Automate connection |
| Handles ambiguity | Yes, the model interprets the request | No, every call is explicit | No, fixed mappings |
| Runs unattended | With an agent framework | Yes | Yes |
They aren’t exclusive. Many teams keep a scheduled API sync for project and vendor data (or use the native Procore, Autodesk and ProjectSight integrations), and add MCP for the ad-hoc questions and one-off actions that never justified building a feature.
Frequently asked questions
What is the Billy MCP server?
A Model Context Protocol server, hosted at app.billyforinsurance.com/mcp, that lets AI assistants read projects, vendors and contracts in Billy and perform actions such as creating vendors, creating contracts and sending certificate of insurance requests.
Does it work with Microsoft 365 Copilot?
Yes. A Copilot Studio maker adds the Billy server as an MCP tool to an agent and publishes it to Microsoft 365 Copilot and Teams. Users with a Microsoft 365 Copilot licence then add the agent and ask questions in plain language.
Which other AI tools work with it?
Any MCP-compatible client: Claude (web, desktop, Claude Code), ChatGPT, Cursor, and agent frameworks that support remote MCP servers over streamable HTTP.
Does it need an API key?
No. Claude and ChatGPT users sign in with their Billy login the first time the client connects. In Copilot Studio, the agent registers itself with Billy automatically; end users still sign in as themselves and get their own Billy permissions.
Can an AI assistant change a vendor’s compliance status through MCP?
Only on your instruction. The assistant can save a review decision you have made, such as approving or rejecting a certificate against a requirement, and Billy then recalculates compliance as it would for a review saved in the app. The decision is recorded as yours, and the assistant does not save one on its own.
Can it delete data?
No. The only “removal” available is archiving a vendor with update_vendor, which is reversible.
Is there a sandbox?
Yes. A demo server with sample data is available at demo.billyforinsurance.com/mcp. Contact support for access.
Ask Copilot about your subcontractors
See the Billy agent running in Microsoft 365 Copilot, or connect Claude in under five minutes.
Request a demo