Esc

↑↓ move↵ openIndex · Pagefind
Agents / Set up the MCP preview

Set up the MCP preview

Connect an MCP client to os.construction with the hosted server or the local connector, and register hosted clients as an operator.

Preview

Partly in the app today. Items marked Planned are not built yet.

On this page

The MCP connector lets a client discover an operation, inspect its inputs and call the os.construction REST API as you. It keeps the initial tool list small and loads endpoint details only when needed. Three tools are always available: os_search_operations, os_describe_operation and os_read. os_write appears only when writes are enabled.

Choose a connection

Connection How it signs in Status
Hosted server at https://app.os.construction/mcp Browser sign-in and Allow access (OAuth) Preview; live in production and read-only for the first release.
Local connector (osc mcp) Personal API token in the client’s environment settings Preview; works today. The connector ships in the @os-construction/cli npm package (npx -y @os-construction/cli mcp).

Both use the same operation catalog and the same permission checks. Neither gives a client more access than your account has.

Run the local connector

Create a personal token in Account > AI assistants > Personal API tokens. Keep Read-only (recommended) unless the assistant must change records. Configure your MCP client to launch:

npx -y @os-construction/cli mcp

and set these environment variables for that process:

Variable Value
OS_CONSTRUCTION_API_TOKEN Your personal token; required.
OS_CONSTRUCTION_API_URL https://app.os.construction by default; use your approved test environment when testing.
OS_CONSTRUCTION_MCP_ALLOW_WRITES Leave unset for read-only use. Set to true only with a read-and-write token when you intend to allow changes.
OS_CONSTRUCTION_MCP_ALLOW_HTTP_LOOPBACK Leave unset normally. Set to true only for an HTTP development server on loopback.

Most clients take a JSON block like this one for Claude Desktop (claude_desktop_config.json) or Cursor (mcp.json):

{
  "mcpServers": {
    "os-construction": {
      "command": "npx",
      "args": ["-y", "@os-construction/cli", "mcp"],
      "env": { "OS_CONSTRUCTION_API_TOKEN": "paste-your-token-here" }
    }
  }
}

The token determines the account used by the API. A login in your browser does not change that account. Do not use a shared administrator token or paste a credential into a chat prompt. The command does not print a welcome screen: it waits for an MCP client on standard input and keeps standard output for protocol messages.

Run the connector from source

Use a trusted checkout of the os.construction repository and Node.js 24 or newer. From the repository’s app directory:

npm ci
npm run mcp:catalog
node --import tsx scripts/mcp-stdio.ts

Configure your MCP client with command node, arguments --import, tsx and scripts/mcp-stdio.ts, the working directory set to the absolute path of app, and the environment variables above. This direct command keeps package-manager output out of the protocol stream. If your client requires the npm script, use npm run --silent mcp:stdio; on Windows, use npm.cmd when the host cannot execute npm directly.

Check the connection

Ask your client to search for RFI read operations. It should use os_search_operations, then os_describe_operation on a returned operation ID. Describe returns the operation’s documented parameters and request schema, including whether it requires an OS-Company-Id header; RFI operations do.

Choose a project you can access and ask the client to read a small first page with os_read. When the contract requires OS-Company-Id, the local connector takes your company’s ID as the top-level companyId argument, a positive safe integer; the hosted server fills it in from your sign-in. Check the company, project ID and returned records against the app. companyId never changes your identity or grants access, and a successful search alone does not prove access to project data.

Continue with MCP workflows and MCP permissions and troubleshooting.

Hosted client registration

These controls are for os.construction platform operators. Customers do not register clients; they connect an approved assistant from Account > AI assistants.

Approve the common assistants

Platform console > MCP clients > Recommended AI clients lists reviewed registrations for Claude, Claude Code, ChatGPT, VS Code, Cursor and the osc CLI. Register read-only registers one with a read-only ceiling: catalog discovery plus every configured read scope.

Claude, Claude Code, ChatGPT and VS Code identify themselves with a client ID metadata document, an HTTPS URL such as https://claude.ai/oauth/mcp-oauth-client-metadata. When the server sets MCP_OAUTH_CIMD_ENABLED=true, its discovery metadata tells these clients to send that URL, so users only paste the server URL. os.construction never fetches the document during sign-in: the registration’s callback URLs were reviewed from each vendor’s published document and are matched exactly, except that local loopback callbacks may use any port. Clients that are not registered see This app is not approved yet. Dynamic client registration is not offered.

Cursor does not publish such a document, so Cursor users add "auth": { "CLIENT_ID": "os-construction-cursor" } to their configuration.

Register a client manually

A platform super administrator opens Platform console > MCP clients at /admin/platform/mcp-clients. A workspace administrator without the platform role cannot open this page.

  1. Choose Register a client and enter the exact client ID sent by the client, plus a name users can recognize on the consent page.
  2. Choose a callback mode and enter up to ten callback URLs, one per line. Exact HTTPS callback matches each URL exactly. Native loopback callback is for http://127.0.0.1/path or http://[::1]/path without a port; only the local port may vary. Public AI client accepts exact HTTPS URLs, loopback URLs on 127.0.0.1, [::1] or localhost with any port, and reviewed app schemes such as cursor://anysphere.cursor-mcp/oauth/callback. Do not use a wildcard.
  3. Enter the necessary operation scopes separated by spaces. Expand Configured scopes to review the server’s available choices. Catalog discovery is added automatically; operation scopes define the client’s maximum request, not permission to act for every user.
  4. Choose Register client and review the saved callback URLs and scope ceiling. Registration records the operator. The client registration is immutable: a changed callback or broader ceiling requires a new client ID and fresh user consent.

If the server scope registry is unavailable, new registration is disabled, but existing clients can still be retired. To end a client’s access platform-wide, choose Retire client, review the warning, then Confirm retirement. Retirement is permanent, records the operator and revokes every grant for that client. The retired client cannot start a new authorization.

Registration does not replace user consent. A user starts the connection in a registered client, signs in to os.construction, reviews the named client and requested scopes, and chooses Allow access or Deny. Only an approved grant permits the client to attempt operations within the user’s existing access. No client should ask the user to paste their application password into a chat.

Users can review or revoke their own grants in Account > Connected apps. See connection revocation for the exact steps and the distinction from local API tokens.

Coverage and rollout

The preview discovers cataloged JSON operations supported by both the API contracts and route implementations. Catalog revision 2b7478125d87ef8dead46a61 contains 2,191 operations and 386 exclusions. These are catalog coverage counts, not proof that every operation has passed a live integration test or is available to your user. Regeneration can change the counts.

Coverage does not include every route, multipart upload, binary export or streaming response. Hosted MCP has a separate optional stored-upload metadata tool and bounded native download path; these do not change the JSON catalog counts. Six GET definitions with branches requiring write scope are excluded until dedicated adapters can enforce the appropriate inputs and access rules. If an operation cannot be found, do not invent an operation ID or send an arbitrary URL.

A local release rehearsal ran the compiled application through HTTPS and the signed ingress handler with a simulated hosting edge. Browser and SDK checks covered platform-only registration, user consent, credential refresh, an authorized RFI read, account revocation and client retirement. After revocation, the next SDK call returned HTTP 401 and refresh was rejected; a retired client could not start a new authorization. These checks used synthetic data and isolated local services. They do not establish the actual hosting edge, private networking, complete client compatibility or public production availability. Use the local connector above until the hosted connection is switched on.

Optional hosted file metadata

When the native transfer rollout is enabled, hosted MCP may expose os_file_info({uploadId}). Obtain the upload ID only from the exact own-site /rest/v1.0/uploads/<id> link returned by an authorized owning-tool response. Do not substitute another record’s attachment ID or pass an arbitrary URL.

The tool returns metadata, a fixed authenticated download URL and a receipt. It does not return file bytes or a public/presigned link. A separate bearer-authenticated request to /mcp/files/<id> rechecks live access. The native CLI download workflow saves the file to an explicit new local path without loading binary data into context.

This optional path requires MCP_OAUTH_ENABLED=true, MCP_HOSTED_ENABLED=true and MCP_CLI_OAUTH_ENABLED=true, plus compatible streaming storage. It is limited to stored uploads of at most 64 MiB within 60 seconds; live S3 integration, other binary workflows and multipart upload support remain unverified or incomplete. Local stdio tools and the JSON catalog remain separate.

Company setup reference discovery

Use module company_admin to discover reviewed company reference operations. Begin with a specific GET search, describe one result and read a bounded page with the exact authorized workspace company_id. The existing stage list remains in admin. See the company setup workflow; writes require more than discovery or admin:write alone.

Candidate file staging

Native OAuth file staging for documents, emails, submittals and bidding is documented in the staging workflow. It stages an unbound upload for a separate supported attachment operation, with explicit write guards and bounded transfers. Scoped local PostgreSQL and CLI checks cover candidate staging and status; production availability and broader storage-provider coverage remain unverified. Existing JSON catalog counts are unchanged.

For the candidate Action Plans, Commitments and Documents tranche, begin with the bounded workflow review. The current catalog includes the new tranche; existing native file guidance and live authorization checks still apply.

Preview 8 adds Specifications, Notifications and Managed Equipment workflows. Use the bounded discovery and permission guidance, including the caller-specific notification inbox behavior.

Preview 9 adds Budget, Change Orders and WBS coverage. Begin with the financial workflow review, including private SOV access, inherited WBS ownership and the catalog exclusion for unsafe line-item-type deletion.

For the preview 10 company governance, Photos metadata and Bidding tranche, begin with the workflow and permission review. Invitation writes record data without dispatching email; recycle PATCH soft-deletes. Run osc coverage to see the catalog revision your installed package carries.

Keep exploring

Related across os.construction

Run it on your own project.

Start a 14-day free trial. Want a say in what ships next? Join the founding program.

Your role (optional)

14-day free trial. Pricing for paid plans isn't set yet. Talk to us. Already have an account? Sign in →

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file