Esc

↑↓ move↵ openIndex · Pagefind
AI agents & CLI

Put an agent on the job.
Keep a person on the hook.

Connect Claude, ChatGPT, Cursor, VS Code or your own code to os.construction through MCP or the osc command. It reads what you can read, drafts what you could draft, and stops at every approval.

  • MCP & CLI: Preview
  • Hosted MCP: on
  • Hosted writes: off
  • npm: @os-construction/cli 0.2.0
  • Built-in agents: Planned

Status comes from the same source as /status. Built-in os.construction agents are Planned; this page is about bringing your own.

osc 0.2.0 · real output

No token needed. The catalog ships in the CLI.

osc operations search --query rfis --method GET --limit 3
{
  "version": 1,
  "command": "operations search",
  "ok": true,
  "data": {
    "revision": "3eff1ae8265e875c4faf0ccc",
    "total": 20,
    "operations": [
      {
        "id": "get_15044a0daf945e479ef5",
        "summary": "List available RFI status filter options"
      },
      {
        "id": "get_59ccee5a4ed9663e0bd7",
        "summary": "List RFI Default Distribution"
      },
      {
        "id": "get_5bc3e16e3092b7234fae",
        "summary": "List available RFI filters"
      }
    ],
    "nextCursor": "…"
  }
}
echo $?
0  # output trimmed
2,341operations in the catalog
60modules, from RFIs to the ledger
115scopes to narrow a token
0things an agent can approve
Sixty seconds

Install nothing. Or install once.

@os-construction/cli 0.2.0 needs Node.js 24 or newer and has no runtime dependencies. The command is osc; the MCP connector is osc mcp. Searching the catalog needs no account.

Pick your OS
npx -y @os-construction/cli operations search --query "change events" --limit 5

# or install it once
npm i -g @os-construction/cli
osc version
Connect

Pick your assistant. Copy. Done.

Every snippet matches Account > AI assistants in the app, which also shows which path your workspace can use right now.

Claude Desktop today with a token; claude.ai web, desktop and mobile through the hosted connector.

Works today · read-only preview

Hosted connector (claude.ai, Desktop, mobile)

  1. In Claude open Settings > Connectors and choose Add custom connector. On Team and Enterprise plans an Owner adds it under Organization settings > Connectors, then each member chooses Connect.
  2. Name it os.construction and paste https://app.os.construction/mcp. Keep the authentication options Claude detects.
  3. Choose Connect, sign in to os.construction and choose Allow access.
Works today

Claude Desktop with a personal token

  1. In os.construction open Account > AI assistants > Personal API tokens. Name it (say Claude on my laptop), keep Read-only (recommended), pick 7, 30 or 90 days and choose Create token. It is shown once.
  2. In Claude Desktop choose Settings > Developer > Edit config and add the server below to claude_desktop_config.json. Node.js 24 or newer must be installed.
  3. Restart Claude Desktop, then ask: "Search os.construction for RFI operations and list the open RFIs on project 123."
claude_desktop_config.jsonJSON
{
  "mcpServers": {
    "os-construction": {
      "command": "npx",
      "args": [
        "-y",
        "@os-construction/cli",
        "mcp"
      ],
      "env": {
        "OS_CONSTRUCTION_API_TOKEN": "paste-your-token-here"
      }
    }
  }
}

The config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

What can it do

2,341 operations. Generated, not guessed.

Straight from the operation catalog in the os.construction source (revision 3eff1ae8265e): 1,064 reads and 1,277 writes across 60 modules. 222 API definitions are deliberately left out (non-JSON bodies, unsafe paths, missing contracts). The npm package 0.2.0 carries revision 2b7478125d87 with 2,191 operations; newer ones arrive with each CLI release. osc coverage shows what yours has.

RFIs, submittals, drawings, specs, meetings, documents and the rest of the project record.

Reads
186
Writes
201
Agents can propose
129
Person only
72
RFIs20 GET13 writes
  • GETList RFIs/rest/v1.0/projects/{project_id}/rfisRead
  • GETShow RFI/rest/v1.0/projects/{project_id}/rfis/{id}Read
  • GETList Recycled RFIs/rest/v1.0/projects/{project_id}/rfis/recycle_binRead
  • GETList available RFI filters/rest/v1.0/projects/{project_id}/rfis/filter_optionsRead
  • GETList RFI Replies/rest/v1.0/projects/{project_id}/rfis/{rfi_id}/repliesRead

Scopes rfis:readrfis:write

osc operations search --module rfis lists all 33.

Submittals12 GET11 writes
  • GETList Submittals on a project/rest/v1.1/projects/{project_id}/submittalsRead
  • GETShow Submittal/rest/v1.1/projects/{project_id}/submittals/{id}Read
  • GETGET /rest/v1.0/projects/{project_id}/submittal_packages/rest/v1.0/projects/{project_id}/submittal_packagesRead
  • GETList Submittal Statuses/rest/v1.0/companies/{company_id}/submittal_statusesRead
  • GETList of deleted Submittals/rest/v1.1/projects/{project_id}/submittals/recycle_binRead

Scopes submittals:readsubmittals:write

osc operations search --module submittals lists all 23.

Drawings18 GET20 writes
  • GETList drawing sets/rest/v1.0/projects/{project_id}/drawing_setsRead
  • GETList drawing areas/rest/v1.0/projects/{project_id}/drawing_areasRead
  • GETList drawing areas/rest/v1.1/projects/{project_id}/drawing_areasRead
  • GETList drawing revisions/rest/v1.0/projects/{project_id}/drawing_revisionsRead
  • GETList drawings/rest/v1.0/drawing_areas/{drawing_area_id}/drawingsRead

Scopes drawings:readdrawings:write

osc operations search --module drawings lists all 38.

Specifications25 GET21 writes
  • GETList Specification Sections/rest/v1.0/specification_sectionsRead
  • GETGet a specification section/rest/v1.0/specification_sections/{id}Read
  • GETList Specification Section Divisions for a Project/rest/v1.0/specification_section_divisionsRead
  • GETList Specification Section Revisions for a Specification Section Division/rest/v1.0/specification_section_revisionsRead
  • GETList recycled specification sections/rest/v1.0/specification_sections/recycle_binRead

Scopes specifications:readspecifications:writesubmittals:write

osc operations search --module specifications lists all 46.

Meetings12 GET20 writes
  • GETList meetings/rest/v1.0/meetingsRead
  • GETShow meeting/rest/v1.0/meetings/{id}Read
  • GETList meeting categories/rest/v1.0/meeting_categoriesRead
  • GETGet the minutes and date created for all parent topics/rest/v1.0/meeting_topics/parent_minutesRead
  • GETList meetings/rest/v1.1/projects/{project_id}/meetingsRead

Scopes meetings:readmeetings:write

osc operations search --module meetings lists all 32.

Documents7 GET15 writes
  • GETList files visible to the caller in a project/rest/v1.0/filesRead
  • GETList project folders and files/rest/v1.0/foldersRead
  • GETShow project File/rest/v1.0/files/{id}Read
  • GETShow Project Folder/rest/v1.0/folders/{id}Read
  • GETList version history for a document file/rest/v1.0/files/{id}/versionsRead

Scopes documents:readdocuments:write

osc operations search --module documents lists all 22.

Emails11 GET6 writes
  • GETShow Communication/rest/v1.0/communications/{id}Read
  • GETList Communication Threads/rest/v1.0/communications/{communication_id}/threadsRead
  • GETShow Communication Thread/rest/v1.0/communications/{communication_id}/threads/{id}Read
  • GETShow Email Communication/rest/v1.0/project/{project_id}/email_communications/{id}Read
  • GETShow Company-level Email Communication/rest/v1.0/companies/{company_id}/email_communications/{id}Read

Scopes emails:reademails:write

osc operations search --module emails lists all 17.

Correspondence8 GET5 writes
  • GETList Correspondence Types/rest/v1.0/companies/{company_id}/generic_toolsRead
  • GETList Correspondence Type Items/rest/v1.0/projects/{project_id}/correspondence_type_itemsRead
  • GETShow Correspondence Type/rest/v1.0/companies/{company_id}/generic_tools/{generic_tool_id}Read
  • GETRecycle Bin/rest/v1.0/projects/{project_id}/recycle_bin/correspondence/itemsRead
  • GETList Correspondence Items/rest/v1.0/projects/{project_id}/generic_tools/{generic_tool_id}/generic_tool_itemsRead

Scopes correspondence:readcorrespondence:write

osc operations search --module correspondence lists all 13.

Transmittals3 GET7 writes
  • GETList visible project transmittals/rest/v1.0/transmittalsRead
  • GETGet a visible transmittal/rest/v1.0/transmittals/{id}Read
  • GETList recycled project transmittals/rest/v1.0/transmittals/recycle_binRead
  • POSTCreate a transmittal/rest/v1.0/transmittalsAgents can propose
  • POSTCreate a transmittal from documents or drawings/rest/v1.0/transmittals/create_fromAgents can propose

Scopes transmittals:readtransmittals:write

osc operations search --module transmittals lists all 10.

Tasks6 GET5 writes
  • GETList task items/rest/v1.0/task_itemsRead
  • GETShow task item/rest/v1.0/task_items/{id}Read
  • GETList Task Items Assignee options/rest/v1.0/task_items/assigneesRead
  • GETList Assignees for Accessible Tasks/rest/v1.0/task_items/assignees/currentRead
  • GETList Task Item Comments/rest/v1.0/companies/{company_id}/projects/{project_id}/task_item_commentsRead

Scopes tasks:readtasks:write

osc operations search --module tasks lists all 11.

Action plans15 GET32 writes
  • GETGET /rest/v1.0/projects/{project_id}/action_plans/plans/rest/v1.0/projects/{project_id}/action_plans/plansRead
  • GETGET /rest/v1.0/projects/{project_id}/action_plans/parties/rest/v1.0/projects/{project_id}/action_plans/partiesRead
  • GETGET /rest/v1.0/projects/{project_id}/action_plans/plans/{id}/rest/v1.0/projects/{project_id}/action_plans/plans/{id}Read
  • GETGET /rest/v1.0/projects/{project_id}/action_plans/plan_approvers/rest/v1.0/projects/{project_id}/action_plans/plan_approversRead
  • GETGET /rest/v1.0/projects/{project_id}/action_plans/plan_receivers/rest/v1.0/projects/{project_id}/action_plans/plan_receiversRead

Scopes action_plans:readaction_plans:write

osc operations search --module action_plans lists all 47.

Coordination issues6 GET3 writes
  • GETGET /rest/v1.0/coordination_issues/rest/v1.0/coordination_issuesRead
  • GETGET /rest/v1.0/coordination_issues/{id}/rest/v1.0/coordination_issues/{id}Read
  • GETGET /rest/v1.0/coordination_issues/assignees/rest/v1.0/coordination_issues/assigneesRead
  • GETGET /rest/v1.0/coordination_issues/recycle_bin/rest/v1.0/coordination_issues/recycle_binRead
  • GETGET /rest/v1.0/coordination_issues/filter_options/status/rest/v1.0/coordination_issues/filter_options/statusRead

Scopes coordination_issues:readcoordination_issues:write

osc operations search --module coordination_issues lists all 9.

Models7 GET5 writes
  • GETList BIM models/rest/v1.0/projects/{project_id}/bim_modelsRead
  • GETShow BIM model/rest/v1.0/projects/{project_id}/bim_models/{bim_model_id}Read
  • GETFederated model composition (file-bound revisions)/rest/v1.0/projects/{project_id}/bim_models/federated_modelsRead
  • GETList revisions/rest/v1.0/projects/{project_id}/bim_models/{bim_model_id}/revisionsRead
  • GETList viewpoints/rest/v1.0/projects/{project_id}/bim_models/{bim_model_id}/viewpointsRead

Scopes models:readmodels:write

osc operations search --module models lists all 12.

Forms11 GET7 writes
  • GETList Forms on a project/rest/v1.0/projects/{project_id}/formsRead
  • GETList Forms on a project/rest/v1.1/projects/{project_id}/formsRead
  • GETShow Form/rest/v1.0/projects/{project_id}/forms/{id}Read
  • GETList Company Form Templates from Project/rest/v1.0/projects/{project_id}/form_templatesRead
  • GETList Company Form Templates/rest/v1.0/companies/{company_id}/form_templatesRead

Scopes forms:readforms:write

osc operations search --module forms lists all 18.

Photos10 GET14 writes
  • GETList images/rest/v1.0/imagesRead
  • GETList catalog tags for a project/rest/v1.0/image_tagsRead
  • GETShow image/rest/v1.0/images/{id}Read
  • GETList image categories/rest/v1.0/image_categoriesRead
  • GETList tags assigned to a photo/rest/v1.0/images/{id}/tagsRead

Scopes photos:readphotos:write

osc operations search --module photos lists all 24.

Locations2 GET3 writes
  • GETList Project Locations/rest/v1.0/projects/{project_id}/locationsRead
  • GETShow Project Location/rest/v1.0/projects/{project_id}/locations/{location_id}Read
  • POSTCreate Location (Admin)/rest/v1.0/projects/{project_id}/locationsAgents can propose
  • DELETEDelete Project Location/rest/v1.0/projects/{project_id}/locations/{location_id}Person only (admin)
  • PATCHUpdate Project Location/rest/v1.0/projects/{project_id}/locations/{location_id}Agents can propose

Scopes locations:readlocations:write

osc operations search --module locations lists all 5.

Conversations2 GET3 writes
  • GETList conversations the caller participates in/rest/v1.0/projects/{project_id}/conversationsRead
  • GETShow a conversation with a bounded message window/rest/v1.0/projects/{project_id}/conversations/{id}Read
  • POSTCreate a conversation/rest/v1.0/projects/{project_id}/conversationsAgents can propose
  • POSTPost a message to a conversation/rest/v1.0/projects/{project_id}/conversations/{id}/messagesAgents can propose
  • PATCHMark a conversation read for the caller/rest/v1.0/projects/{project_id}/conversations/{id}/readAgents can propose

Scopes conversations:readconversations:write

osc operations search --module conversations lists all 5.

Project archive2 GET1 write
  • GETList project data exports/rest/v1.0/projects/{project_id}/data_exportsRead
  • GETShow a data export/rest/v1.0/projects/{project_id}/data_exports/{id}Read
  • POSTCreate (generate) a data export/rest/v1.0/projects/{project_id}/data_exportsAgents can propose

Scopes project_archive:readproject_archive:write

osc operations search --module project_archive lists all 3.

Direct uploads2 GET2 writes
  • GETShow a local nonsegmented upload/rest/v1.1/projects/{project_id}/uploads/{uuid}Read
  • GETShow a local nonsegmented upload/rest/v1.1/companies/{company_id}/uploads/{uuid}Read
  • POSTInitiate a local nonsegmented upload/rest/v1.1/projects/{project_id}/uploadsAgents can propose
  • POSTInitiate a local nonsegmented upload/rest/v1.1/companies/{company_id}/uploadsAgents can propose

Scopes uploads:readuploads:write

osc operations search --module direct_uploads lists all 4.

Notifications3 GET5 writes
  • GETList the caller's notification inbox/rest/v1.0/projects/{project_id}/notificationsRead
  • GETList a project's notification recipient rules for a tool/rest/v1.0/projects/{project_id}/notifications/settingsRead
  • GETGet the caller's notification preferences/rest/v1.0/projects/{project_id}/notifications/preferencesRead
  • POSTCreate or update a project notification recipient rule/rest/v1.0/projects/{project_id}/notifications/settingsPerson only (admin)
  • POSTMark notifications in the caller's inbox read/rest/v1.0/projects/{project_id}/notifications/mark_readAgents can propose

Scopes notifications:readnotifications:write

osc operations search --module notifications lists all 8.

Email intake4 GET3 writes
  • GETList the email intake log/rest/v1.0/projects/{project_id}/email_intake/messagesRead
  • GETList inbound email addresses/rest/v1.0/projects/{project_id}/email_intake/addressesRead
  • GETShow an email intake log entry/rest/v1.0/projects/{project_id}/email_intake/messages/{id}Read
  • GETShow an inbound email address/rest/v1.0/projects/{project_id}/email_intake/addresses/{id}Read
  • POSTCreate an inbound email address/rest/v1.0/projects/{project_id}/email_intake/addressesPerson only (admin)

Scopes admin:readadmin:write

osc operations search --module email_intake lists all 7.

Under the hood

Four tools. One loop.

The connector does not dump 2,341 tool definitions into your model's context. It exposes a handful of tools and lets the model look things up:

  • os_search_operationscompact summaries, 20 at a time, with a cursor
  • os_describe_operationone operation's exact path, query and body schema
  • os_readruns a GET as you; responses are capped and marked when truncated
  • os_writeonly when writes are enabled; needs confirmed: true and never retries

Plus a usage resource that teaches the workflow and a project-review prompt. Returned record text is treated as data, never as instructions.

A typical sessionMCP
1. os_search_operations   {"query": "change events", "method": "GET"}
2. os_describe_operation  {"operationId": "get_4d45ca2e79f0ef5552d6"}
3. os_read                {"operationId": "get_4d45ca2e79f0ef5552d6",
                           "companyId": 10, "query": {"project_id": 123, "per_page": 10}}
4. (with your OK)  os_write {"operationId": "post_ce700bbc11af5c71540a", "confirmed": true, ...}
Safety model

Six gates between a prompt and your ledger.

Agents get the same permissions as the person behind them, minus the ability to say yes. Security & privacy has the details.

  1. Scopes

    Narrow before you start

    Every assistant token is scoped and expires. Read-only covers the 58 read scopes; read-and-write adds writes except webhooks and company administration.

    • Tokens last 7, 30 or 90 days, up to 10 active per person
    • Only a SHA-256 hash is stored; the token is shown once
    • Scopes narrow your access. They never add to it
  2. Consent

    You say yes, explicitly

    Hosted connections open os.construction in your browser: you sign in, read what the assistant asks for, and choose Allow access or Deny.

    • Hosted grants last up to 14 days, then ask again
    • Hosted connections are read-only in the preview
    • The assistant works as you: your projects, your records
  3. Propose-only

    Agents draft. They do not decide.

    Assistant tokens and hosted connections are agent credentials. Of 1,277 cataloged writes, 636 are proposals agents may make; 635 approve or administer and answer 403 for any agent.

    • Approve, certify, execute, post, pay, release, void, delete: refused
    • Setting status: "approved" through an update: refused
    • 6 transition endpoints allow only their submit-style actions
  4. Human approval

    A person signs off in the app

    The draft lands where your team already works. Someone with the approve permission reviews it in os.construction, exactly as if a colleague had drafted it.

    • "Agent credentials can create and propose changes but cannot approve…"
    • Approval rules and roles are unchanged
    • Built-in os.construction agents are Planned and will follow the same rule
  5. Audit

    Every call leaves a trail

    Agent calls are recorded with the person they act for. Company admins review proposals and refused attempts under Company admin > API activity.

    • Tracked edits keep field-level before and after
    • Hosted calls return an invocation ID you can look up
    • Service accounts have their own call log
  6. Revoke

    One click, effective on the next call

    Revoke a token in Account > AI assistants, or a hosted connection in Account > Connected apps. Changing your password or two-factor settings revokes all of your tokens.

    • Deactivating a user ends their tokens too
    • Company admins can revoke apps company-wide
    • Receipts survive revocation for review
Cookbook

Work orders for your agent.

All 12 recipes →

Keep going

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