Connect your AI agent

Contractors Cloud provides an MCP server that lets you connect AI agents — like Claude or ChatGPT — directly to your Contractors Cloud account. Once connected, your agent can look up customers, manage projects and tasks, work with contracts, estimates, work orders, invoices, and payments, build and run reports against your live data, and answer product questions from our official help documentation, all in plain conversation. MCP endpoint: https://api.contractorscloud.com/mcp

​

What’s MCP?

MCP (Model Context Protocol) is an open standard that lets AI agents securely interface with external services. Most major AI platforms support it. Connecting is a one-time setup: on platforms with a connector directory, like Claude, find Contractors Cloud there and add it in a couple of clicks; otherwise, paste the Contractors Cloud endpoint into your AI platform manually. Either way, you sign in with your normal Contractors Cloud credentials and approve the connection — no API keys or developer setup required.

​

What your agent can do

Once connected, your agent has access to tools for the following (this list will grow over time):

• People & teams — look up users and teams by name, so you can say “assign it to Mike Kampa” or “give it to the install crew” instead of hunting down an ID
• Contacts — search your contacts; create and update them; link an existing contact to an account, project, or user
• Customer accounts — search accounts; create and update them
• Projects — search projects, create projects with the correct setup options, update existing ones, and add project notes
• Project photos & files — search a project’s files and add new ones
• Tasks — search tasks; create, update, and complete them
• Appointments — search appointments; schedule and reschedule them, with invites to attendees
• Contracts — search contracts; create and update them, approve or unapprove them, and lock or unlock their payouts
• Estimates — search estimates and their line items; create and update estimates, and add, change, or remove their line items
• Work orders — search work orders; create and update them, including crew assignment and install dates
• Material orders — search material orders, including by reference number or supplier; create and update them, and manage their line items
• Invoices, payments & credit memos — search them and their lines; create and update invoices and credit memos, record and apply payments, and add, change, or remove their lines
• Jet Streams — search Jet Streams, start a new one, or reply to an existing one, notifying the people on it
• Inbox mail — search the messages in your inboxes, and look up an inbox’s own email address — the one to hand out when mail needs to come in, like a project’s intake address
• Reports — find and run your saved reports, and build new ones when none of them fits the question (see Reports and analytics)
• Help & how-to — search and read Contractors Cloud’s official help documentation, so your agent can answer “how do I…” questions about the product itself

Your agent can also look up the valid choices for the fields on these financial records — trades, types, statuses, tax codes, payment methods, and so on — so it doesn’t have to guess. You refer to people, teams, projects, and customers by name — your agent looks up whatever internal IDs it needs on its own. If a name is ambiguous, it should ask you which one you meant rather than guess. A few examples of what you could ask:

• “Find the customer account for the Hendersons and add a note to their active project.”
• “Create a task on the Justin Cross project assigned to Mike Kampa — order a dumpster for Monday.”
• “What roofing projects were created this month? Run my Production Pipeline report.”
• “We don’t have a report for this — what’s our total expense amount across every active job?”
• “Create an invoice on the Alvarez contract for the first progress billing, due in 30 days.”
• “Schedule a final walkthrough with the Alvarez job for Thursday at 2pm.”
• “How do I connect QuickBooks Online to Contractors Cloud?”

​

Reports and analytics

Reporting is how your agent answers questions about your live data, and it works two ways. Running a report you already have. Your agent can find any report you can open in the web app — your own, ones shared with you, and the out-of-the-box reports — and run it for a page of rows or for its totals. Totals (sums, averages, counts, minimums, and maximums) are calculated in one pass over every record the report matches, not just the page in front of you, so asking “what’s the total” doesn’t mean reading through thousands of rows. A report only totals the columns it’s already set up to total — on a report you own, your agent can add a missing sum or average itself. Building a report when none of yours fits. If no saved report answers the question, your agent can build one: it looks up what’s available to report on — over twenty record types, including projects, invoices, estimates, payments, expenses, bills, tasks, appointments, work orders, material orders, milestones, and permits — along with the columns and filter conditions each one supports, then creates the report, runs it, and adjusts its columns and filters as you refine the question. Date filters can use rolling periods like “this month” or “this quarter”, so a report built once keeps reporting on the current period every time it runs. A few boundaries worth knowing:

• A report your agent creates is always private to you. It can’t make one company-wide or share it with a teammate. Visibility, sharing, and a report’s KPI cards are managed in the web app, where you can see who the audience actually is.
• Out-of-the-box reports can’t be changed by an agent. To tailor one, make a copy of it in the web app, or ask your agent to build a new report with the columns and filters you want.
• Cleanup is limited to your own scratch reports. A report built to answer a single question can be deleted once you’re done with it, but only if you created it, it’s still private, and you haven’t shared it — and deletion is permanent. If a one-off report looks worth keeping, say so; it’ll sit alongside your other reports in the web app, where you can rename it, share it, or adjust its KPI cards.

​

Financial records

Some things are always worked out by Contractors Cloud, so your agent can’t set them directly:

• Totals and balances. Invoice, credit memo, and estimate totals, invoice balances, and how much of a payment has been applied are calculated from the lines, payments, and credits. Your agent changes the lines; the totals follow. The same goes for a contract’s sold amount, which comes from its invoices, not from an estimate.
• Work order progress. Your agent can’t mark a work order In Progress, Complete, or Closed Pending. Those statuses are set by Contractors Cloud itself as the work progresses.
• Material order status. A material order’s status follows its supplier and delivery dates, and its PO number is generated for you.
• Whether a payment counts. A new payment starts as Pending, which doesn’t reduce an invoice’s balance. Only a payment moved to a status that counts as paid, such as Deposited, does, so ask your agent to confirm with you before it marks a payment as deposited.

​

What your agent can access

Your agent acts as you. It signs in with your identity and inherits your exact permissions and your company’s data boundaries — it can only see and change what you can see and change. It can never access another company’s data, and it can’t do anything your own account couldn’t do in the app. Connections are available to standard Contractors Cloud users only. System administrator accounts and customer portal (homeowner) accounts can’t connect an agent. When you approve the connection, the only permission granted is “Access the MCP server as your user.” You can review it on the approval screen before accepting. Financial tools follow your account’s finance permissions. If your permissions hide project finances from you, your agent can’t create, change, or delete invoices, payments, or credit memos, and money amounts are left out of what it reads. Some actions need their own permission, such as approving a contract, locking its payouts, or deleting a credit memo.

​

Requirements

• An active Contractors Cloud account (standard user)
• An AI platform that supports remote MCP servers (see below)

​

Connect your agent

​

Staying connected

After you approve the connection, your agent stays signed in automatically for up to 30 days at a time — behind the scenes, short-lived credentials are refreshed for you. If your agent reports that its Contractors Cloud connection has expired, reconnect — you’ll be asked to sign in and approve again.

​

Security and control

• Review what your agent does. Your agent can create and update contacts, accounts, projects, notes, files, tasks, appointments, reports, and financial records (contracts, estimates, work orders, material orders, invoices, payments, and credit memos), and can start Jet Streams. Some actions notify real people: a Jet Stream messages everyone on it, an appointment can email invites to attendees (including customers), and assigning a task can notify the assignee. Most AI platforms show you what a tool call is about to do before it runs; keep those confirmations on, especially at first, and above all for anything involving money, such as recording a payment, approving a contract, or deleting an invoice. You’re responsible for actions your agent takes as you.
• What it can delete. Your agent can delete a report (only one you created that is still private and unshared, typically one it just built to answer a question) and these financial records:
  • Work orders, only while they’re in Draft. Deleting one also removes its material orders and the expenses billed against them; the bills those expenses were on are updated to match.
  • Material orders, only when no supplier is assigned.
  • Contracts, only when nothing is attached to them: no invoices, payments, payouts, expenses, work orders, material orders, permits, or vendor services.
  • Estimates. Nothing blocks this, and your agent can’t bring one back.
  • Invoices, only when no payment and no credit memo is applied to them.
  • Payments and credit memos. Nothing blocks these. Deleting a credit memo also needs the permission to delete credit memos.
  Deleting a contract, work order, or material order is permanent. Deleted invoices, payments, and credit memos are hidden rather than erased, but your agent can’t restore them, so contact support if one was removed by mistake. Your agent can also remove individual lines from an estimate, material order, invoice, payment, or credit memo, and those removals are permanent. Nothing else can be deleted through an agent: no contact, account, project, note, file, task, appointment, Jet Stream, company-wide report, or out-of-the-box report.
• QuickBooks isn’t touched. Your agent never sends anything to QuickBooks. Deleting an invoice, payment, or credit memo removes Contractors Cloud’s link to its QuickBooks copy, but the copy in QuickBooks stays as it is, so your bookkeeper may need to void or delete it there. Deleting a work order or material order removes the QuickBooks links of the expenses it deletes in the same way.
• Changes ripple through the project. Financial changes recalculate the project’s totals and the payouts that depend on them, and may re-run the project’s workflow. Contractors Cloud also adds a note to the project’s activity log for most of these changes, which is how you can see what the agent did.
• Your permissions are the ceiling. The agent can never see or do more than your own account allows.
• Disconnect any time. Remove the connector from your AI platform’s settings to stop all access. Access also ends on its own if you don’t re-approve after the sign-in period expires.

​

Troubleshooting

• “…available to standard users only” (403) — you’re connecting with a system administrator or customer portal account. Connect with your regular Contractors Cloud user instead.
• Sign-in page never appears — double-check the URL is exactly https://api.contractorscloud.com/mcp, and that your platform supports remote MCP servers with OAuth sign-in.
• Redirect/registration error during sign-in — your platform’s callback address isn’t on our approved list yet; contact Contractors Cloud support and tell us which platform you’re using.
• Agent says the connection expired — reconnect from your platform’s connector settings; you’ll sign in and approve again.
• A tool call fails — wait a minute and try again; if it persists, contact Contractors Cloud support with the approximate time and what your agent was doing.