MCP Connector

The MCP Connector lets an external AI client —Claude Desktop, Cursor, or Claude Code — securely read (and, for a focused set of safe drafts,write) a customer’s BuildTools data through a scoped, audited connection.

MCP (“Model Context Protocol”) is a standard way for AI assistants to plug into external tools. With the connector enabled and a key issued, a user can ask their AI assistant things like “what’s the state of the Maple Street project?” or “list my open RFIs” and the assistant pulls the answer from BuildTools — limited to exactly what the key is allowed to do.

create_task — create a task on a project (title required; optional description, priority, due date, assignee).
​update_task_status — move a task to a new status.
​draft_rfi — create a DRAFT RFI (subject + question); not opened, notifies no one.
​draft_change_order — create a DRAFT change order (title, description, type, amount, optional line items); leftunnumbered/unsent until a PM sends it, notifies no one.
​create_project — create a new project (name required; optional status/type/number/address/dates/contract amount/client contact).
​update_project — update safe project metadata only (name, status, type, number, description, address, dates, client contact). Does not touch financial rollups. add_budget_line_item — add a line item to a budget. Enforces one line per cost code (returns the existing line instead of creating a duplicate) and recalculates budget totals. Uses the same logic as the BuildTools UI.
​draft_daily_report — AI-draft a DRAFT daily report for a project + date. Skips dates that already have a report, are in the future, or precede the project start; notifies no one. Requires the org’s AI drafting to be configured.

Make sure the MCP Connector is enabled in settings

Then enable the API key

After creating a key, add it to the AI client’s MCP config. Example for Claude Desktop ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

The exact endpoint URL and a copy-ready snippet are shown in the MCP Connector tab right after you create the key. Cursor / Claude Code use the same endpoint + Bearer header.

A. Enable + create a key

1. Super-admin: confirm mcp_connector_enabled is ON at /admin/settings. 2. As an org admin:Settings → MCP Connector → Create key→ choose Read-only → (optionally restrict to one project) → create. 3. Copy the key + the JSON snippet from the show-once modal (the secret is shown only once).

B. Connect the AI client

1. Paste the snippet into the client’s MCP config → restart the client. 2. Ask the assistant to “list available BuildTools tools” → confirm only the read tools appear (the write tools are hidden for a read-only key).

C. Read tests (the core value)

1. “List my projects in BuildTools.”→ expect results. 2. “Give me a snapshot of .” → expect live counts (open tasks, pending COs, open RFIs, outstanding invoices). 3. “List open RFIs / recent invoices / the working budget / recent daily reports for .”→ expect data. 4. In Settings → MCP Connector → Audit log, confirm matching rows with status OK and latency.

D. Write tests (drafts + low-risk creates)

1. Create a key with the Full template; reconnect. 2. “Create a task ‘Order windows’ on .”→ success + anOK audit row for create_task . 3. “Draft an RFI asking about the beam size on .”→ a DRAFT RFI (confirm in the UI it’s DRAFT and nobody was notified). 4. “Draft a change order for $1,500 of extra framing on .”→ a DRAFT CO with no CO number yet (number is assigned when a PM sends it). 5. “Create a project called ‘Test Cabin’.”→ a new project in PLANNING; then“rename it to ‘Lakeside Cabin’ and set status In Progress.” 6. “Add a ‘Lumber’ line item to the working budget for .”→ line added; repeat for the same cost code and confirm it returns the existing line (no duplicate). 7. “Draft yesterday’s daily report for .”→ a DRAFT daily report (requires AI configured; otherwise returns created: 0 with a note).

E. Denial test (proves scoping)

1. Using the Read-only key, ask the assistant to create a task or draft a change order. 2. Expect it to be unavailable/refused, and an audit row with status DENIED.

F. Project allowlist test

1. Create a key restricted to Project A only. 2. Ask to draft a change order or updateProject B → expect it blocked; Project A works.

G. Asset safety check

1. With assets:read, ask for a project’s photos/documents. 2. Confirm you get metadata (names, types, sizes) —not file contents or download links.

H. Lifecycle: revoke / deactivate / global off

1. Toggle a key Inactive (or Revoke) → the client’s next call fails auth. 2. (Optional) Set a near-term expiry and confirm it stops working after it lapses. 3. Flip the global switch OFF at /admin/settings → confirm all MCP calls return service unavailable, then turn it back on.

For questions or help on getting your company's MCP connector configured please reach out to Support