QSME for AI assistants (MCP)
QSME is an MCP server. Connect Claude, ChatGPT, Claude Code, Codex or Cursor and your assistant can read your projects and prepare work in them — read the schedule of quantities, draft a tender from it, keep a spreadsheet up to date, answer a question out of your drawings — without you copying anything between windows.
This page is the whole surface: how to connect, what an assistant is allowed to do, every tool with its arguments, and the house rules to put in a prompt.
The line that never moves. An assistant can draft; a person decides. Nothing on this page can move money, publish a tender, accept a bid, award work or issue a contract. Those doors are not wired to MCP at all — not gated behind a flag, not available with a better token. A draft stays private in QSME until you publish it yourself.
Connecting
The server is https://api.qsme.co.nz/mcp, registered as qsme. The set-up page with copy-paste commands for each client is qsme.co.nz/connect.
claude mcp add --transport http qsme https://api.qsme.co.nz/mcp{
"mcpServers": {
"qsme": {
"type": "http",
"url": "https://api.qsme.co.nz/mcp",
"headers": { "Authorization": "Bearer ${QSME_TOKEN}" }
}
}
}Sign in with your QSME account when the client asks. The assistant works as you: it sees exactly what you see, on the projects you are on, and nothing else. A project being public does not make its schedules, sheets or money readable.
Scopes
| Scope | What it allows |
|---|---|
| read | Every get_, list_, find_ and search tool. |
| write | The add_, create_, update_, import_ and delete_ tools as well. |
A token with read alone can never change anything: a write tool refuses with required_scope, and says which scope it needed.
Where to start
list_projects gives you project ids. Almost every other tool takes one.
Amounts are New Zealand dollars, excluding GST, unless a field says otherwise. Dates are YYYY-MM-DD.
Projects, drawings and search
| Tool | What it does | Scope |
|---|---|---|
list_projects | The projects you own or work on. Start here. | read |
get_project | One project: address, status, units, who is on it. {project_id} | read |
get_schedule | The site schedule: tasks, dates, who is on each, what follows what. {project_id} | read |
query_drawing_knowledge | Ask a question of the analysed consent drawings and get an answer with the pages it came from. | read |
search | Across projects, SOQ, tenders, contracts and sheets. | read |
fetch | One record by the id search returned. | read |
search and fetch use prefixed ids — a sheet is sheet:<project>/<sheet> — so an assistant can go from a search hit straight to the thing.
The SOQ — the estimate
The SOQ is pockets → jobs → material and labour lines. It is what tenders are cut from, so this is usually where work starts.
| Tool | What it does | Scope |
|---|---|---|
get_soq | The whole schedule as a tree, with ids and totals. {project_id} | read |
add_soq_category | A tender pocket. {project_id, name, description?, activate?} | write |
add_soq_job | A job in a pocket. {project_id, category_id, title, specifications?, weather_sensitive?} | write |
add_soq_material | A material line. {project_id, job_id, name, quantity, unit, unit_rate, description?} | write |
add_soq_labour | A labour line. {project_id, job_id, description, est_hours, hourly_rate, notes?} | write |
update_soq_job · update_soq_material · update_soq_labour | Change one, by its id. | write |
delete_soq_item | Remove a job, a material line or a labour line. {project_id, item_id} | write |
Units are normalised to m, m2, m3, lm, no, item, ea, kg, t, lot, sum, hr; anything else becomes item. Totals are worked out, not written — add the lines and the totals follow. A new pocket is a draft unless activate is set, which is the right default.
Tenders — always a draft
| Tool | What it does | Scope |
|---|---|---|
list_tenders | Tenders you created, or on projects you own — drafts included. | read |
get_tender | One tender: scope, budget, dates, and its items. | read |
create_tender_draft | A draft tender. | write |
add_tender_draft_items | Put SOQ jobs into that draft, so bidders price your lines. | write |
update_tender_draft | Edit the draft — title, scope, dates, budget. | write |
A draft is private to you. Publishing it, inviting anyone, and awarding it are done by a person in QSME.
Contracts — always a draft
| Tool | What it does | Scope |
|---|---|---|
list_contracts | Contracts on your projects. | read |
get_contract | One contract: parties, scope, amount, milestones. | read |
create_contract_draft | A draft direct contract: title, scope, amount, dates. | write |
update_contract_draft | Edit that draft. | write |
Issuing a contract, and every payment under it, is a person's act in QSME.
Sheets — the builder's own spreadsheets
Sheets are free-form spreadsheets per project: payment trackers, wages, expenses, variations, estimate against actual.
| Tool | What it does | Scope |
|---|---|---|
list_sheets | Folders, sheets and tabs, with ids and row counts. {project_id} | read |
get_sheet | A tab, worked out — formulas evaluated, links resolved — keyed by column name and id. Paged. | read |
get_sheet_summary | Totals and the money broken down by status, without reading every row. | read |
get_sheet_suggestions | What the platform thinks the tab could use. Proposals only. | read |
find_sheet_rows | Lines matching a query, with their ids. | read |
list_link_targets | What a line could link to: soq_job, tender, contract, payment, schedule_item. | read |
create_sheet | A new sheet with tabs, columns and optional first lines. | write |
import_sheet_csv | A whole sheet from CSV text — far cheaper than a rows array. | write |
add_sheet_tab | Another tab. | write |
add_sheet_rows | Lines, cells keyed by column heading. | write |
update_sheet_rows | Change lines by id — cells, heading text, highlight, bold. | write |
set_sheet_columns | Replace a tab's columns. Takes the rev from get_sheet. | write |
create_estimate_vs_actual | Build the estimate-against-actual sheet from the project. | write |
delete_sheet_rows · delete_sheet | Remove lines; soft-delete a sheet. | write |
A sheet only records. Marking a line Paid does not pay anybody and does not touch the Money ledger.
House rules worth putting in your prompt
Never invent a figure. Measuring a building and setting rates are the quantity surveyor's job. Where a quantity or rate is unknown, write the line unpriced — 0 and 0 — and say which lines need a price. A confident wrong rate is worse than a gap.
Read before writing. Ids come from get_soq, get_sheet and list_sheets. A job id is not a line id.
Say what you changed. "Added 14 lines to Plumbing → First fix, total $18,400 ex GST" is checkable; "updated the SOQ" is not.
Drafts, then ask. Draft the tender, then tell the person to look at it and publish it themselves. Do not imply you sent anything.
Stale writes are refused, not merged. set_sheet_columns takes the rev you last read; if someone changed the tab meanwhile you get a refusal telling you to read it again. Do that rather than retrying blindly.
Headings, not guesses. Sheet cells are keyed by column heading or column id. A heading that is not in the tab is refused by name, so read the error — it lists the columns that do exist.
Money is masked per person. Someone who may not see a project's money gets names without amounts. If figures come back as 0 with has_amount false, that is permission, not an empty project.
GST. Rates are ex-GST. New Zealand GST is 15%. The GST inside a GST-inclusive figure is 3/23 of it.
What an assistant cannot do
| Not available over MCP | Where it happens |
|---|---|
| Move, send or release money | The Money page, by a person |
| Publish a tender or invite bidders | The tender, by a person |
| Accept a bid or award work | The bid review, by a person |
| Issue a contract | The contract, by a person |
| Change someone else's project | Not at all — you only see your own |
This is deliberate and it is not configurable. If an assistant tells you it has sent, paid or awarded something, it has not.
Words used on this page
| Word | Meaning |
|---|---|
| MCP | Model Context Protocol — how an AI client connects to a tool server like QSME. |
| Tool | One action the assistant can take, with named arguments. |
| Scope | read or write — what a connection is allowed to do. |
| Draft | Made but not published. Private to you until you publish it in QSME. |
| SOQ | Schedule of Quantities — the estimate. |
| Sheet | A free-form spreadsheet inside a project. |
Questions: hello@qsme.co.nz.