MCP permissions and troubleshooting
Understand which identity the MCP preview uses, how API permissions apply, and how to handle failures without broadening access.
Partly in the app today. Items marked Planned are not built yet.
On this page
- What determines access
- Agents propose; people approve
- Troubleshoot a call
- Report a problem
- Review or revoke a hosted connection
- Review an invocation receipt
- Stored-upload access
- Company setup permissions
- Stage a file through the native CLI
- Workflow authorization and record visibility
- Specifications, Notifications and Managed Equipment
- Budget, Change Orders and WBS boundaries
- Company governance, photo metadata and bidding
The local MCP preview calls the REST API with the API token configured for its process. The API evaluates that token and the associated user’s access on each request. Catalog search is a description of possible operations; it is not a list of permissions granted to you.
What determines access
The actual REST route remains responsible for its authorization checks. Depending on the operation, these include token scope, active user, token expiry, company ownership, project membership and role, enabled project tools, record visibility, and workflow-specific rules. A write-enabled connector does not grant any of these permissions.
For operations declaring OS-Company-Id, the local connector accepts companyId as a positive safe integer and requires it when the contract requires that header. The API checks this assertion against the company authorized by your token. An arbitrary headers object is not accepted, and changing the assertion cannot grant another company’s access. Hosted dispatch derives company identity from its authenticated OAuth actor and rejects a conflicting assertion; that implementation does not establish a public hosted release.
Use an explicitly scoped token with only the capabilities needed for the task. Existing unscoped API tokens may have broad access subject to normal application checks; the connector does not automatically reduce them to a least-privilege grant. Your administrator should review the token before using it with a client.
An API token is a secret. Keep it out of prompts, source control, screenshots, recordings, and support tickets. Local client configuration may store environment variables as plaintext; use a secret facility where your client provides one and restrict access to the configuration.
See Roles and permissions for the application permission model.
Agents propose; people approve
Hosted MCP connections and personal tokens created under Account > AI assistants are agent credentials. They can read and create or draft work, but approval, certification, posting, payment, release, void, delete, Recycle Bin and permission or configuration endpoints answer 403 with the message “Agent credentials can create and propose changes but cannot approve…”, even when the token has the scope. A request that tries to set an approval state through an ordinary update (for example status: "approved") is refused the same way. A person completes those steps in os.construction. Company admins can review agent proposals and refused attempts under Company admin > API activity.
Troubleshoot a call
| Symptom | What to check |
|---|---|
| The local process exits before connecting | Confirm Node.js and dependencies are installed, the working directory is app, and the token is present in the process environment. |
| No records appear after search | Search returns operation metadata. Describe an operation, then make a read call for the selected project. |
| An expected GET operation is absent | Some GET routes contain branches requiring write access. Six such definitions are excluded pending dedicated adapters; absence is not a reason to construct a raw URL or change credentials. |
| Authentication fails or the API returns 401 | Confirm the token is current and belongs to an active user. Replace an expired or revoked credential through your administrator’s approved process. |
| Access is denied or the API returns 403 | Check token scopes, project permissions, tool enablement, workspace restrictions, and any operation-specific rules. Do not switch to an administrator credential merely to bypass the denial. |
| The API returns 404 | Check the selected project and record IDs. Missing or inaccessible records should not be treated as proof that a record exists elsewhere. |
| Inputs are rejected | Describe the current operation again and check its path, query, and body schema. |
company_id_required |
Supply the top-level companyId required by the operation’s OS-Company-Id contract. Use your authorized company ID, not the project ID. |
invalid_company_id |
Use a positive safe integer only on an operation declaring OS-Company-Id. Do not pass a string, arbitrary headers, or another company’s ID. |
| The API returns 429 | Stop issuing calls and respect the service’s rate-limit guidance before retrying. |
| A result exceeds the output limit | Narrow the query or request a smaller page. Treat the answer as incomplete until the required pages have been inspected. |
| A response is not JSON or requires a redirect | Use a supported operation. Stored uploads have the separate bounded native download workflow below; arbitrary redirects and general file transfer remain unsupported. |
| A write times out or loses its response | Check the record and history before repeating it; the result may be unknown even if a change committed. |
Report a problem
Include the operation ID, sanitized parameters, approximate time, response status, and request identifier if one was returned. Remove tokens, personal information, financial payloads, and private record text unless your approved support channel requires them. Say whether the issue happened during discovery, a read, or a write.
Review or revoke a hosted connection
Open Account > Connected apps at /account/connected-apps. Sign in with the account that approved the connection. The page lists that user’s current connections, their client names, granted scopes, approval times and expiry times. Dates are shown in UTC. Use Next page when more connections are available.
- Find the intended connection and review its client name and scopes.
- Choose Revoke access to reveal the confirmation.
- Choose Confirm revocation. A successful action shows Connection revoked and removes that grant from the current list.
The revoked grant can no longer authenticate new calls. If the client registration remains active, the client needs fresh approval to reconnect. Revoking one connection does not retire the registered client platform-wide or revoke another user’s grant. Platform super administrators use MCP clients > Retire client > Confirm retirement for permanent client-wide retirement.
A local stdio connector uses a separate REST API token. Revoking a hosted grant does not revoke that token; use the token administrator’s approved procedure to end local access.
If the page reports that revocation could not be saved, refresh the list and retry through the account controls. Do not treat a failed save or an empty page reached with a pagination cursor as proof that every grant has been revoked.
Review an invocation receipt
Open Account → Connected apps → Invocation history. Enter the invocation ID returned by the hosted MCP or CLI request, or select an outcome. Workspace administrators can switch the view to Workspace activity for their current workspace. Revoking a connection preserves its receipts for review.
Use the receipt to find the operation, status and time of the request. For a pending or unknown write, confirm the result in the affected tool before retrying.
Stored-upload access
Optional hosted os_file_info({uploadId}) is metadata only. It returns a fixed URL and receipt, but the next request to /mcp/files/<id> must authenticate independently. A successful metadata lookup, a copied URL or an earlier receipt does not grant continued access after permissions or the OAuth grant change.
Use only the upload ID from an exact own-site /rest/v1.0/uploads/<id> exposed by an authorized owning-tool response. Do not substitute an attachment ID, arbitrary URL or storage path. Access includes the actual owning records and their tool scopes; uploads:read is only the scope requirement for an unbound upload and does not bypass other checks. A missing or inaccessible file may be reported simply as unavailable.
Native CLI downloads require OAuth mode, an explicit new destination and the native rollout flags. They preserve existing files and report JSON path, bytes, SHA-256 and an optional receipt. Limits are 64 MiB and 60 seconds. See CLI download permissions. S3 needs an explicit strict streaming adapter and remains unverified live; other binary and multipart workflows remain open.
Company setup permissions
Company reference operations use path.company_id from the authorized workspace. admin:read permits the scoped read attempt; admin:write still requires the user’s live company capability for the mutation and normal workspace restrictions. Neither changing the company ID nor enabling connector writes grants another workspace’s access. Review the company setup workflow before making changes.
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.
Workflow authorization and record visibility
Action Plans, Commitments and Documents operations retain live project and record checks. A plan sign-off requires authorization for the actual actor; neither a broad scope nor a supplied user ID permits signing for someone else. Commitment change-order drafts do not imply approval, execution or payment authority. Document staging, attachment, version review and ACL checks are distinct steps; transferred bytes do not override folder or document access. Confirm restore availability and its authorization through the installed catalog before use.
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
- DocsWork with the MCP previewUse discovery, schemas, bounded reads, and reviewed writes to work with construction records through the local MCP preview.
- 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.
- 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.
- GlossaryAI AgentSoftware that uses an AI model to carry out multi-step tasks, like reading documents, checking data and drafting actions, toward a goal.
- 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.
- 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 →