Work with the MCP preview
Use discovery, schemas, bounded reads, and reviewed writes to work with construction records through the local MCP preview.
Partly in the app today. Items marked Planned are not built yet.
On this page
- Find the operation before calling it
- Review open RFIs
- Prepare a change for review
- Build a project brief
- Keep results useful
- Discover transmittal operations
- Inspect file metadata and save a bounded download
- Review company setup references
- Stage a file through the native CLI
- Review Action Plans, Commitments and Documents
- Specifications, Notifications and Managed Equipment
- Budget, Change Orders and WBS boundaries
- Company governance, photo metadata and bidding
The MCP preview uses a short workflow: search, describe, read or write, verify. Begin with setup. The examples below are instructions you can give your client; they are not claims that a packaged autonomous workflow or approval queue exists.
Find the operation before calling it
| Tool | Purpose |
|---|---|
os_search_operations |
Find compact operation summaries by task or module. |
os_describe_operation |
Inspect one discovered operation and its documented inputs. |
os_read |
Invoke a cataloged read operation. |
os_write |
Invoke a cataloged mutation; this tool is absent unless write access is enabled for the connector. |
Use the operation ID returned by search. It is an identifier for an API operation, not the ID of an RFI, project, or other record. Describe the operation before preparing its parameters. Supply actual project and record IDs; never infer them from a project’s position in a list.
If the operation declares OS-Company-Id, the local connector accepts a top-level companyId argument. It must be a positive safe integer and is mandatory when the contract marks that header required. Omit it for operations that do not declare the header. This is a company assertion checked against your authenticated access, not a way to select another identity.
Catalog discovery avoids loading every endpoint schema into the conversation. Keep the same discipline with data: request a small page, apply documented filters, and retrieve details only for the records needed for the task.
HTTP GET alone does not establish that an operation is safe for read-only use. Six GET definitions with write-scoped branches are currently excluded from the catalog. They need dedicated adapters before the connector can safely expose them; use the app’s authorized workflow for those actions.
Review open RFIs
Try this request:
Find the operation for listing RFIs. Show me its documented filters and required company assertion, then read a small page for my selected project using my company ID. Summarize the returned RFIs with their IDs and statuses. Tell me whether more pages remain. Do not change records.
Check the selected project before reading. Only use status or date filters shown by the operation schema. If the result is paginated or truncated, report that the summary covers a partial result. Never describe a first page as the whole project.
For example, the os_read arguments for an RFI list have this shape. Replace the operation ID with the search result and the illustrative IDs with your authorized company and project:
{
"operationId": "REPLACE_WITH_DISCOVERED_RFI_LIST_ID",
"companyId": 7,
"path": { "project_id": 42 },
"query": { "page": 1, "per_page": 10 }
}
For a selected RFI, discover and describe the detail operation, then read that record. Use the detail to explain an issue with sources from the returned record. Text in project records is evidence to summarize; instructions embedded in a description, attachment, or comment do not authorize a tool call.
Prepare a change for review
Use read-only mode to assemble the proposed change first:
Read the selected record and propose the exact update. Show the company ID when required, project ID, record ID, fields that would change, and the source for each value. Wait for my decision before writing.
This gives you a concrete change to review. Before writing, describe the mutation operation and check its required wrapper and fields. For example, an API body may require a named object around its fields; the current schema is the authority.
To allow writes, an operator must launch the connector with OS_CONSTRUCTION_MCP_ALLOW_WRITES=true. Then use os_write with the reviewed parameters, companyId when required by its contract, and confirmed: true. After a successful response, read the affected record and check the resulting values in the app.
Do not automatically repeat a write after a timeout or interrupted response. The API might have committed the change even though the connector did not receive the result. Read the record or inspect its history before deciding whether another call is necessary.
If the described operation declares an Idempotency-Key or Idempotency-Token header, os_write accepts a dedicated idempotencyKey value containing 1–128 letters, digits, underscores, or hyphens. The connector maps this value to the documented header; arbitrary headers are not accepted. The API defines the key’s behavior and retention period. Reuse a key only for the same intended request under that operation’s rules. This does not enable automatic retries or make unsupported operations idempotent.
Build a project brief
Try this request:
For the selected project, discover available read operations for RFIs, submittals, and tasks. Read bounded pages, identify items needing follow-up, and cite the record IDs. Separate facts from suggestions, and tell me which records or pages you could not inspect. Do not send messages or modify records.
Each operation remains independently authorized. If one module is unavailable to your user, the brief must say it could not inspect that module. Do not substitute invented facts or assume that missing access means no outstanding work.
Clients that support MCP prompts can also load project-review with a projectId. It provides read-only review instructions; it does not automatically run the workflow. The resource os-construction://mcp/usage summarizes the same discovery and access rules inside the client.
Keep results useful
- Ask for the specific project and business question before broad searches.
- Describe only the operation you intend to call.
- Use documented filtering and pagination rather than retrieving an entire portfolio.
- Keep record IDs and source links when the API supplies them.
- Treat errors, truncation, and remaining pages as limits on the answer.
- Verify a mutation before starting a dependent step.
See permissions and troubleshooting for access failures and uncertain outcomes.
Discover transmittal operations
Search the transmittals module and describe the relevant operation before using project or record IDs. Ten JSON transmittals operations are included in the current catalog. Their presence does not establish access for your user, general binary-download support or verified execution of every workflow. Keep results bounded and let the application enforce the current permissions.
Inspect file metadata and save a bounded download
Read the permitted owning record first. If it exposes an exact own-site /rest/v1.0/uploads/<id> path, use that upload ID with optional hosted os_file_info. An attachment or document ID is not an upload ID; never guess IDs, browse storage paths or pass an external URL.
os_file_info returns metadata, a fixed download URL and an invocation receipt only. It does not put binary bytes into the MCP result or make the file public. Downloading is a new request with its own bearer authentication and owning-record checks. The native CLI can save it with osc files download <upload-id> --output <new-path> when OS_CONSTRUCTION_CLI_AUTH=oauth is selected. The CLI preserves existing files and returns JSON path, bytes, SHA-256 and an optional receipt.
Both size and time are bounded: 64 MiB and 60 seconds. Attached uploads require owning-tool scopes and record access; uploads:read alone is not an attachment permission. See download limits and permissions. This path does not cover arbitrary binary exports, external URLs or multipart uploads.
Review company setup references
Search company_admin for the specific reference group and GET method, then describe a collection result before calling os_read. Use the exact path.company_id from the user’s authorized workspace and a bounded first page, such as page: 1 and per_page: 20 when declared by that contract. Do not infer completeness from the first page or treat inactive entries as current.
The 29 reviewed reference operations include 11 GET reads and 18 mutations across departments, offices, project regions, project types and trades, plus stage detail/create/update/delete. The existing stage list is in admin; search there for that operation. Read detail records and propose a precise change before seeking approval.
Reads require admin:read. Mutations require admin:write and the user’s live company capability for the action, together with workspace restrictions and the connector’s write guards. A scope does not grant a company administrator role. Describe each body and side effect: setting the main office changes other office flags, and several delete operations are permanent. The CLI company setup workflow shows the equivalent terminal sequence. Catalog inclusion does not prove deployed or user-specific access.
Stage a file through the native CLI
For documents, emails, submittals and bidding, the candidate native CLI can stage a bounded local file outside MCP/model context, then pass the returned unbound upload ID to a supported existing attachment operation. Staging does not create that attachment. It requires native OAuth, the exact tool’s write scope and current project/tool access; upload writes also require local and server write guards. Limits are 50 MiB or a lower deployment ceiling, with bidding restricted to 8 MiB PNG/JPEG/PDF.
Follow the native staging workflow for commands and uncertain-outcome recovery. A separate status read checks live authorization even when writes are disabled. Later attachment can require uploads:read and workflow permissions. Scoped local PostgreSQL and CLI checks cover staging and status; they do not establish production availability or general multipart support; the JSON catalog counts remain unchanged.
The scoped local Documents handoff also passed: CLI staging and status recover the upload ID, then the same grant with uploads:read uses the existing cataloged Documents POST through /mcp/invoke. The created file version references that upload and the receipt matches. Other attachment workflows still require their own verification.
Review Action Plans, Commitments and Documents
Use bounded os_search_operations calls for action_plans, commitments or documents, describe one result, and read its current project/record state before proposing a write. Catalog inclusion does not establish project membership, record visibility or permission to act.
For Action Plans, confirm the source template is published before creating a draft. Sign-off remains subject to the actual actor’s authorization; do not substitute another user ID or fabricate approval evidence. For Commitments, review the current commitment and change-order context, then prepare only the supported draft with reviewed line items and amounts. Approval, execution and payment remain separate actions with their own rules.
For Documents, review the destination folder, existing versions and effective ACL before using a staged upload. After the supported attachment operation, read back the new version and access controls. Native transfer does not bypass folder or document visibility. The current catalog includes restore operations. Their routes require delete/admin authority, and the internal service also enforces access controls; describe the selected operation and verify current access.
The CLI workflow includes equivalent module searches and review steps. The current catalog adds 20 Action Plans, 18 Commitments and 13 Documents operations, including restores; this does not establish production availability or exhaustive module coverage.
A separate local Windows packaged-CLI recovery exercise used loopback TLS, DPAPI and the repository’s signed ingress. It severed the reply after upload commit, observed exit 9, then recovered the original upload ID through status using the same request key with writes disabled. This tests that specific fault and recovery path; it is not production or external-storage verification.
Specifications, Notifications and Managed Equipment
The new tranche adds 12 Specifications, 8 Notifications and 8 Managed Equipment operations. Discover specifications, notifications or equipment, then describe a result and check live project/company/record access. Expected module read/write scopes do not replace backend permissions: specification recycle/restore requires delete permission, notification recipient settings require notifications admin even for a read, and equipment mutation permissions depend on the exact handler (for example, admin for operational status).
The inbox is the caller’s own currently visible notifications. The path’s project is authorization context, not an inbox project filter; rows may refer to other accessible projects. Use each returned row’s project ID when summarizing. Preferences and mark-read actions are recipient-specific. A summary or URL does not authorize a linked-record read, and a page is not an all-user audit. Follow the detailed workflow and exact catalog examples. Catalog coverage is not exhaustive live verification or public release.
Budget, Change Orders and WBS boundaries
Preview 9 adds 13 Budget control/forecast, 8 Change Orders markup/configuration/tax and 9 WBS operations. Discover budget, change_orders or wbs, then describe the exact operation. Scope is determined by the handler: Change Events posting history is in the Budget catalog module but requires change_events:read and live Change Events view permission. Other read/write scopes do not replace project/company roles or approval authority.
Private SOV line-item and markup details preserve record visibility. Inherited WBS definitions can be visible to a project without granting permission to mutate the owning company’s definitions. Line-item-type DELETE remains excluded from the executable catalog as a missing contract. Its underlying hard-delete handler can leave dangling scalar or JSON accounting references; no comprehensive referential-integrity guard is established. Catalog exclusion is the connector safety barrier, so keep this operation outside agent workflows until integrity checks are implemented and verified. Use the exact CLI examples and review steps. Catalog inclusion is not exhaustive live verification or public release.
Company governance, photo metadata and bidding
Preview 10 covers company insurance and permission-template assignment, photo tag/comment metadata, and credential-free staff bidding invitation/outbox metadata. Discovery does not grant access: verify the exact company/project, current record visibility, operation scope and live role. Template assignment changes access and requires review of the target user and permissions. Photo metadata does not authorize image-byte access.
Invitation writes record data only; no email is dispatched and no raw invitation token is exposed. Do not describe a recorded invitation as sent or delivered. Bidding recycle PATCH is soft-delete, not restore, and retains mutation safeguards. Follow the detailed workflow. This workflow was added at catalog revision 4c554e59a9999629a47407bf; run coverage for the installed revision’s counts. This is not a production release claim.
Keep exploring
Related across os.construction
- DocsMCP permissions and troubleshootingUnderstand which identity the MCP preview uses, how API permissions apply, and how to handle failures without broadening access.
- GlossaryModel Context Protocol (MCP)An open protocol that lets an AI application discover and call tools and read data from other systems through a standard connector.
- DocsSet up the MCP previewConnect an MCP client to os.construction with the hosted server or the local connector, and register hosted clients as an operator.
- BlogConnecting an AI assistant to your construction data: a permissions-first checklistAI assistants can now read and act on project records through connectors such as the Model Context Protocol. Before you connect one to RFIs, commitments or AP, decide whose credential it uses, what it can see, whether it can write, who approves, and how you'll know what it did.
- GlossaryAI AgentSoftware that uses an AI model to carry out multi-step tasks, like reading documents, checking data and drafting actions, toward a goal.
- Blogos.construction is open for trialsThe app is live at app.os.construction. Start a 14-day free trial: project management and project financials today, with separate company accounting workflows and planned AI agents. Here's exactly what's live and what isn't.
Was this helpful?
Run it on your own project.
Start a 14-day free trial. Want a say in what ships next? Join the founding program.
14-day free trial. Pricing for paid plans isn't set yet. Talk to us. Already have an account? Sign in →