Esc

↑↓ move↵ openIndex · Pagefind
Troubleshooting & FAQ

Something said no. Here is why.

Find your symptom, apply the fix. Exit codes and envelopes are listed in full on the CLI reference.

My assistant does not show any os-construction tools

Restart the client after editing its config. Check that node --version prints 24 or newer in the environment the client launches (GUI apps may not see your shell's PATH; use the full path to npx in command if needed). Run npx -y @os-construction/cli mcp yourself: without a token it prints "set OS_CONSTRUCTION_API_TOKEN…" and exits 2, which proves the package runs.

osc mcp: set OS_CONSTRUCTION_API_TOKEN in your MCP client's environment settings

The token must be in the env block of the client config (or VS Code's promptString input), not in your terminal session.

Exit 3: missing_token or HTTP 401

No token in this process, or it expired (7/30/90 days), was revoked, or your password/2FA changed. Create a new one in Account > AI assistants.

Exit 4 / HTTP 403 on a read

The token lacks the scope, or your user cannot see that project, tool or record. Check the scope list in the recipe or with osc operations describe. Do not switch to an admin token to get around it.

Exit 4 / 403 "Agent credentials can create and propose changes but cannot approve…"

Working as designed. Approve, post, pay, void, delete and permission changes need a person in the app (or a service account not marked as an agent).

Exit 4: write_disabled

Writes need both OS_CONSTRUCTION_CLI_ALLOW_WRITES=true and --confirm, and a read-and-write token. For MCP: OS_CONSTRUCTION_MCP_ALLOW_WRITES=true.

Exit 2: "Use read for GET operations and write for mutations."

read only runs GET operations; everything else is write. Check the method in the search result.

Exit 5: unknown_operation

The ID is not in your installed catalog. IDs come from search; a newer or older CLI may have a different catalog, so run osc coverage and search again.

company_id_required or invalid_company_id

Add a top-level companyId (a number) when describe marks OS-Company-Id required. Use your company ID from the app URL, not the project ID.

output_too_large / truncated: true (exit 10)

One envelope holds at most 32 KiB. Lower per_page, add filters, or use serializer_view where the operation offers it. The page was omitted whole, so nothing was dropped silently.

unsupported_response

The operation returns a file or CSV, not JSON. Use the app or plain REST for it (see the WIP CSV recipe).

Exit 9: outcome unknown

A write may have committed. Look for the record before trying again, or resend with the same idempotencyKey. See the recovery recipe.

Exit 7: HTTP 429

Rate limited. Stop, wait (the API sends Retry-After), then continue. Limits are on Limits, paging & errors.

Windows: npx or osc "cannot be loaded because running scripts is disabled"

Use npx.cmd and osc.cmd, or call them from cmd.exe. In MCP configs on Windows, "command": "npx" usually works; if not, use "command": "npx.cmd".

stdin was not complete within five seconds

With --input -, pipe the JSON in (echo {...} | osc read ID --input -). The CLI never waits for interactive typing.

Search returns nothing for something that surely exists

Search is a plain word match over module, summary, path and method, and every word must match. Use fewer words, try singular and plural, or filter with --module.

ChatGPT says it cannot connect

ChatGPT needs the hosted URL and OAuth. Check that ChatGPT is approved for your workspace in Account > AI assistants.

FAQ

Is the os.construction MCP server live?

MCP and the CLI are in Preview. The CLI and its local MCP connector are on npm as @os-construction/cli and work with production today using a personal token. The hosted endpoint at https://app.os.construction/mcp is switched on as a read-only preview. Built-in os.construction agents are Planned.

Which assistants can I connect?

Today: Claude Desktop, Claude Code, Cursor, VS Code (Copilot agent mode) and any MCP client that can launch a local stdio server, plus scripts through the osc CLI. ChatGPT and claude.ai on the web need the hosted connection.

Can an AI agent approve a change order, post a journal entry or pay a bill?

No. Agent credentials can read and propose. 635 cataloged operations that approve or administer return 403 for any agent credential, whatever its scopes. A person approves in os.construction.

Does the assistant see all of my company's data?

It sees exactly what the user behind the token can see, narrowed further by the token's scopes. Projects you are not on, tools turned off and private records stay hidden.

Does the CLI need an account to try?

No. Help, search, describe, modules and coverage run offline from the catalog inside the package. You only need a token to read or write records.

How many operations can an agent use?

The catalog has 2,341 operations across 60 modules (1,064 reads, 1,277 writes). Run osc coverage to see the installed revision and what was excluded and why.

Should I use a personal token or a service account?

A personal token for an assistant working for you. A service account for anything unattended (cron jobs, integrations): it has its own scoped, rotating keys, an optional IP allowlist and its own call log, and it does not depend on one person's account.

Is my data used to train models?

os.construction sends API results only to the client you connected. What your MCP client and model provider do with that data is governed by their terms, so check your provider's settings. The CLI has no telemetry.

What does it cost?

The CLI and connector are free to install. API access comes with your os.construction workspace; see the pricing page for plans.

Still stuck? Send support the operation ID, sanitized input, the time, the HTTP status and any request or invocation ID. Never include the token.

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