Feature · MCP for AI agents
Your AI agents, working inside the job.
Read what is authorised. Draft what is permitted.
VIABUILD can securely connect with compatible AI agents, allowing them to work with authorised information and perform permitted actions inside your construction operating system. Writes preview first, sending and paying stay with a person, and every call is logged.
01 / Plain language
What MCP is, and why an agent is not a chatbot
MCP stands for Model Context Protocol. It is an open standard, published in late 2024 and now maintained as an open source project, that gives an AI application one consistent way to ask another system what it can do and then do it. The system publishes a list of named tools, each with a description and the inputs it accepts. The AI reads that list, picks a tool, calls it, and gets a result it can reason over. Think of a switchboard with a labelled set of lines rather than an open door.
VIABUILD runs an MCP server for each workspace. That is the whole feature. A normal AI assistant can answer questions. An agent connected through VIABUILD’s MCP can work with authorised live business information and perform permitted actions. The difference is the word permitted. VIABUILD decides which tools exist, what each returns, which workspace it is bound to, and which actions are drafts for a person to complete. The agent works inside those lines.
This is not Oryn. Oryn is the intelligence embedded in VIABUILD itself, reading plans and invoices and bringing the right context to the screen you are already on, whether or not anything is connected. MCP is the door that lets the agents your team already uses, in Claude and in tools like it, reach that same shared understanding of the job from outside the app, and hand drafts back in. Agents do not receive unrestricted access, and nothing here changes the judgement on the agents in construction page. An agent prepares, a builder decides.
02 / Read access
What a connected agent can read
Six scopes. A token carries the ones you tick, and nothing outside its own workspace. Amounts are in AUD, and figures such as profitability, supplier spend and claims position are computed on the server, so the agent gets the same numbers the app shows.
Business overview
A whole-workspace rollup. Jobs by status and active contract value, open purchase order commitments, and the invoice, claim, variation and estimate pipelines.
Jobs and claims
Each job with its budget by cost code (budgeted, committed, actual, forecast), purchase orders, progress claims, variations, contracts, schedule, upcoming and overdue tasks, profitability and claims position.
Estimating
Estimates with full line items (cost, markup, sell), quote packages with each supplier’s request status and quoted totals, and the estimating funnel with win rate.
Purchasing and payables
Purchase orders with invoiced and remaining amounts, supplier bills with their PO match and approval state, catalogue prices with preferred supplier and lead times, and spend by supplier.
Contacts
Suppliers, clients and subcontractors by name, with contact details and payment terms. Banking details are never returned.
Documents
Document metadata for a job, what exists, what type it is and where it sits. The connector does not return file contents.
Some things are never returned, whatever the scope. Supplier and subcontractor banking details, the hashes behind approval links, and the raw payloads from document extraction are excluded at the query, not filtered afterwards. The connector reads the same records as the cost tracking, claims and scheduling modules, so an agent’s answer comes from the same figures the app shows rather than a separate copy.
03 / Write access
What an agent can draft, and what it cannot touch
Writes are a separate scope, off by default when a token is created. Every write tool previews unless the call explicitly says otherwise, and the result of a persisted write is a draft in the app, not a sent, approved or paid record.
Draft purchase orders
Create and update draft orders on a job, including your own PO number and the job cost code. Unknown cost codes are refused rather than guessed. Once an order has been sent, its identity is read-only to the agent.
Draft supplier bills
File a supplier bill with its PDF into the accounts payable queue, linked to its purchase order where one exists. It lands as pending, for a person to approve.
Draft progress claims and variations
Create a draft claim against a job or a variation with cost and sell, and record a status. Sending stays in the app.
Jobs, contacts and leads
Create a job, add or update a supplier or client, or log a lead.
Documents and notes
Upload a file to a job folder, or add notes to a draft estimate.
Record-only status
For imports from another platform, an agent can record a status on an order, bill, claim or variation without triggering the send, approval, payment or Xero side effects that status would normally carry.
Not exposed to agents
What the connector will not do, by design
These are not gaps waiting for a later release. They are the line between preparing work and committing the business. Where a write is not available, the connector says so in its reply rather than doing something close.
- Send a purchase order, claim or any email to a supplier or client
- Run an approval workflow, or approve a bill on your behalf
- Mark a bill paid, make a payment, or write anything to Xero
- Change the amounts or identity of a purchase order that has already been sent
- Delete anything other than a draft or prepared purchase order
- Write budget lines, or rewrite the line items of an estimate
- Create a budget, which the product only does by locking an estimate
- Reach any workspace other than the one the token belongs to
04 / Roles and permissions
Who can connect it, and what a token carries
Only an owner or admin of a workspace can create a connector token. Each token is named, so you know which person and which tool it belongs to, and carries a chosen set of scopes. Business overview, jobs and claims, estimating, purchasing and payables, contacts, and writes. The write scope is unticked unless someone ticks it. A token is bound to one workspace on the server side; no tool accepts a workspace as an input, so a token cannot be pointed elsewhere.
The secret is shown once, at creation, and only a SHA-256 hash of it is stored. Rotate issues a new secret in place and the old one stops working the same instant. Revoke kills the token and keeps its row for the audit trail. Each token shows when it was last used, so a forgotten one is easy to spot.
One honest limit. A token carries scopes for the workspace, not the role of the person holding it. Today the control is that only owners and admins can issue tokens at all, and that they choose the scopes. Per-user role scoping, so a viewer’s connector sees exactly what a viewer sees in the app, is on the roadmap and this page will say when it ships.
05 / Human approval
Which actions need a person
Follow one purchase order from an agent’s suggestion to a supplier’s inbox. The connector is involved at the start and absent at the end, and that is the point.
- 01
The agent previews
Asked to raise an order for the frame package, the agent calls create_purchase_order. By default the call returns a preview of what would be written and writes nothing.
- 02
You confirm the draft
When the preview looks right, the agent calls again with dry_run set to false. A draft order now exists on the job, bound to its cost code, numbered the way you asked.
- 03
It appears in VIABUILD as a draft
The order sits in the purchasing module exactly as if a person had drafted it, with the committed cost visible against the budget line.
- 04
A person sends it
Sending to the supplier is an action the connector cannot take. Someone opens the order, checks it and sends it from the app.
- 05
The rest of the flow is unchanged
When the supplier’s invoice arrives, Oryn matches it to the order in the accounts inbox, and the approval and the push to Xero happen where they always did.
The same shape holds for every write. A supplier bill filed by an agent lands as pending in the accounts inbox and waits for approval. A draft claim waits to be sent from the claims module. Nothing an agent does reaches Xero, because the connector has no tool that writes there.
06 / Logging and revocation
Every call logged, every token revocable, rate limited by default
Every tool call is written to an audit table with the token, the workspace, the tool name, whether it succeeded and the time. The arguments an agent passed are deliberately not logged, so the audit trail records activity without copying job data into a second place. Owners and admins can query their workspace’s rows directly. An audit screen inside the app is on the roadmap.
Each token is capped at 60 tool calls per rolling minute. A runaway agent hits the cap and gets a clear error, not a slow workspace. Tokens for a workspace the connector has not been enabled for are inert. The endpoint answers as if nothing exists there, so a probing client learns nothing.
07 / Supported clients and setup
How to connect
Verified with claude.ai custom connectors, Claude Desktop and Claude Code. Any client that supports remote MCP servers over Streamable HTTP should connect the same way; we have not tested every client ourselves.
- 01
Open Settings, Integrations, Claude
Only an owner or admin sees this screen. If the Claude card is not there, the connector has not been switched on for your workspace yet. Ask us and we will enable it.
- 02
Generate a token
Name it for the person and tool that will use it, for example “Sam, claude.ai”. Pick the read scopes it should carry. The write scope is off unless you tick it.
- 03
Copy the connector URL once
The secret is shown a single time and only a hash of it is stored. Treat the URL like a password. If it is ever exposed, rotate it and the old one stops working immediately.
- 04
Add it to your AI client
In claude.ai, Settings, Connectors, Add custom connector, paste the URL. In Claude Code, run claude mcp add with the http transport and the URL. Claude Desktop follows the same custom connector path.
- 05
Ask a small question first
Try get_session, which returns the workspace the token belongs to, then list your jobs. From there the agent can see which tools it has and what each one does.
08 / Real workflows
What you can do with it today
Each of these runs on tools that exist today. None of them requires the agent to send, approve or pay anything.
Monday position, without opening a report
Ask which active jobs are committed beyond budget and by how much. The agent reads job profitability, which VIABUILD computes on the server, and answers with the cost codes that moved.
Before a supplier negotiation
Ask what you have spent with a supplier this year and what is still on open orders. Supplier spend is ranked and totalled from invoiced amounts and open commitments.
A cash-flow call on claims
Ask what has been claimed, paid and remains on each contract. The claims position comes back per job, computed live, so the answer matches what the app shows.
Raising orders from an approved scope
Give the agent a list of packages and suppliers and have it draft the orders, previewing each one. You send them from VIABUILD when you are ready.
Moving off another platform
An agent can draft your historical orders, bills and claims with their original numbers and a record-only status, so the migrated job reads correctly without sending, approving or paying anything.
A site question from the ute
Ask what is starting on a job this week and what is overdue. The schedule and upcoming tasks read across jobs, including critical path and delays.
09 / Current limitations
What it does not do yet
- The connector is switched on per workspace. If you cannot see the Claude card under Integrations, it is not enabled for you yet.
- Tokens are capability URLs, not OAuth. The secret travels in the URL path, which is how custom connectors work today, so treat it as a password and rotate it if exposed. OAuth 2.1 is on the roadmap.
- Tokens do not expire on their own. They live until revoked or rotated.
- A token carries scopes for a workspace, not the role of the person using it. Per-user role scoping, so a viewer’s connector sees only what a viewer sees, is on the roadmap.
- The audit log is queryable by owners and admins but there is no audit screen in the app yet.
- Budget lines and estimate line items cannot be written through the connector. The product treats locked budgets and non-draft estimates as read-only and the connector respects that.
- Documents come back as metadata only. File contents are not downloaded through the connector.
- Each token is capped at 60 tool calls per rolling minute. Purchase order lists page at 100 rows.
- Sending, emailing, approving through a workflow, paying and Xero writes are not available to agents by design, not by omission.
10 / For developers
The technical shape
The server speaks MCP over Streamable HTTP as stateless JSON-RPC. One POST, one JSON response, no sessions, no server-sent events, no long-lived connection. GET and DELETE on the endpoint return 405. The server negotiates protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 and answers initialize, ping, tools/list and tools/call. Batches from older clients are accepted.
Authentication is a capability URL. The token secret is the last path segment of the connector URL, prefixed vbmcp_, and is compared by hash on every request. Unknown, revoked or disallowed tokens receive a 404 with no detail. Tool-level failures come back as results with isError set, not protocol errors, so a client can read the message and retry with corrected arguments. Writes that the product does not support return a typed gap code, not_captured or not_implemented, with a sentence saying why.
Read tools: get_session, get_business_snapshot, list_jobs, get_job, get_job_schedule, list_upcoming_tasks, get_job_profitability, get_claims_position, list_contracts, list_estimates, get_estimate, list_quote_packages, get_quote_package, get_pipeline_analytics, search_product_prices, list_purchase_orders, get_purchase_order, list_invoices, get_invoice, get_supplier_spend, list_progress_claims, get_progress_claim, list_variations, get_variation, search_contacts, get_contact, list_documents, get_document, list_leads. One quirk to know: list_leads is a read, but it is listed under the write scope, so a token needs that scope to call it.
Write scope tools: create_job, update_job, create_contact, update_contact, create_lead, create_purchase_order, update_purchase_order, delete_purchase_order, create_invoice, create_progress_claim, update_progress_claim, create_variation, update_variation, update_estimate, update_budget, upload_document. Each write accepts dry_run, which defaults to true. update_budget currently returns not_implemented in every case, and update_estimate accepts notes on draft estimates only.
Lists page with offset and limit, capped at 100, and return the next offset or null. Money is AUD. GST on claims and variations is computed as one eleventh of the owner amount. The rate limit is 60 calls per token per rolling minute, counted from the audit table. A local stdio bridge to the same tool registry exists for desktop agents; ask us at hello@viabuild.au if you need it.
11 / FAQ
Common questions.
MCP, the Model Context Protocol, is an open standard that gives an AI application a consistent way to discover and call the tools another system offers. VIABUILD runs an MCP server for each workspace, so a compatible agent can list the tools it is allowed to use and call them, with VIABUILD deciding what each tool returns and what it may change.
No. Oryn is the intelligence embedded inside VIABUILD, reading plans and invoices and bringing context to the screen you are on. MCP is the door that lets the AI agents you already use reach the same understanding from outside the app. Oryn works whether or not you connect an agent.
Any client that supports remote MCP servers over Streamable HTTP. We have verified claude.ai custom connectors, Claude Desktop and Claude Code. Other clients that support the same transport should work, but we have not verified each one ourselves, including ChatGPT, so test with a read-only token first.
No. Sending, emailing, approving through a workflow, paying and writing to Xero are not exposed to agents. An agent can draft the order or file the bill; a person sends and approves in the app.
It sees what the token’s scopes allow, within one workspace, and never banking details. Business overview, jobs and claims, estimating, purchasing and payables, contacts and writes are separate scopes, so a token can be as narrow as one of them.
Every tool call, with the token, the workspace, the tool name, whether it succeeded and when. The arguments an agent passed are deliberately not stored, so the log records activity without copying job data. Owners and admins can query it.
Revoke the token under Settings, Integrations, Claude. It stops working immediately and the row is kept for audit. To keep the connection but replace the secret, rotate instead.
No. The connector is part of the platform. It is enabled per workspace, so ask us to switch it on if the Claude card is not showing in your Integrations settings.
12 / Keep reading
The modules an agent works with
13 / Go deeper
Agents, guardrails and the understanding underneath
Why an agent should stop at the commit, what a grounded assistant honestly does, and how VIABUILD holds one understanding of the job for anything, person or agent, to read.
Connect the agents you already use to the jobs you are already running.
Start with 7 days free, the full operating system, real data. $299 for your first month, then $555/mo. Then create a read-only token and ask your agent how your jobs are tracking.