NovaOS MCP
Field guide

Environments, sign-in, organizations and scopes

How novaos-cli resolves environments, how sign-in works, org context, roles, token scopes and the traps around them.

Quick setup (novaos-cli)

Two environments are supported. US staging (staging) is the default. FDE US (fde) is one switch away.

Guided: novaos_workflow_start {"workflow":"setup_cli"} for US staging, or {"workflow":"setup_cli","params":{"env":"fde"}} for FDE US. By hand:

novaos-cli version                     # 2.2.1 or later; `--version` is not a flag
# US staging (default)
novaos-cli env add staging --api-base https://api.staging.novaos.orbitronai.com --iam-url https://id.staging.novaos.orbitronai.com --client-id 7d548iiaxv5qkaksilkay --marketplace-url https://marketplace.staging.novaos.orbitronai.com --label "US staging" --service-environment staging
# FDE US
novaos-cli env add fde --api-base https://api.fde.us.orbitronai.com --iam-url https://id.fde.us.orbitronai.com --client-id 7d548iiaxv5qkaksilkay --marketplace-url https://marketplace.fde.us.orbitronai.com --label "FDE US" --service-environment staging
novaos-cli env use staging             # writes ~/.novaos/config.json "environment"
novaos-cli env show --verbose          # resolved URLs and where each came from
novaos-cli --env staging auth login    # browser sign-in (OAuth + PKCE)
novaos-cli --env staging auth org list
novaos-cli --env staging auth org use <org-id>
novaos-cli --env staging auth whoami   # identity, org, roles
novaos-cli --env staging publisher show  # slug for manifest "publisher"

Always pass --env in scripts. Re-run auth login per environment; sessions are separate.

Switch environment

  • Ask "switch NovaOS to FDE" (novaos_env_use {"env":"fde"}), or back with {"env":"staging"}. It switches novaos-cli and this server together, and every later command targets the new env.
  • novaos-cli 2.2.x keeps ONE sign-in for all envs (~/.novaos/credentials.json). Signing in to FDE replaces the US staging sign-in, and switching back needs a new browser sign-in. auth whoami only decodes the token locally, so it looks valid for the wrong env; calls then get 401. This server checks the token's issuer and says "Signed in to a different NovaOS environment" instead.
  • Organization, publisher, agents, instances and knowledge collections are separate per env. After a switch, run the setup_cli journey with that env: it adds the env, signs in and picks the org, skipping what is done.
  • Publisher slugs differ per env (for example novaos-business-team on US staging, orbitron-fde on FDE). Check novaos_publisher_show after a switch and update publisher in manifest.json before publishing there.
  • Publishing goes to the active env. Check it with novaos_env_show before you publish.

CLI environment model (2.2.x)

  • Only local is built into the CLI. Hosted environments live in ~/.novaos/environments.json (add with novaos-cli env add <name> --api-base ... --client-id ... [--iam-url] [--marketplace-url]).
  • Active env resolution: --env flag (errors if unknown) -> NOVAOS_ENV -> ~/.novaos/config.json environment -> local.
  • TRAP: an unknown name in NOVAOS_ENV or config.json silently falls back to local (localhost). This server always passes --env explicitly and novaos_env_list warns about it.
  • Per-URL overrides: flags --gateway-url etc., or env vars NOVAOS_GATEWAY_URL, NOVAOS_AGENT_OPS_URL, NOVAOS_MCP_OPS_URL, NOVAOS_REVIEW_URL, NOVAOS_IAM_URL, NOVAOS_CONNECTOR_HOST_URL, NOVAOS_CLIENT_ID, NOVAOS_MARKETPLACE_URL.
  • agent list, publisher show and init publisher lookup need a marketplace URL in the env entry. Both presets include one.

Tools: novaos_env_list, novaos_env_setup, novaos_env_use, novaos_env_show.

Sign-in

  • novaos-cli auth login opens a browser (OAuth Authorization Code + PKCE against Logto, callback on localhost:8976-8978, 120 s timeout). Signing in on the website does NOT sign in the CLI.
  • Tokens are stored in ~/.novaos/credentials.json (0600; never print it). Access tokens last ~15 min and refresh automatically 60 s before expiry; one forced refresh on 401, then "Session expired and refresh failed. Run 'novaos-cli auth login'".
  • This MCP server reuses the CLI sign-in (novaos-cli auth token) internally; tokens are never shown to the model.
  • Default CLI scopes include agent:* mcp:tools:* llm:model:* rag:* memory:* connector:* platform:admin (granted only if your roles allow).

Tools: novaos_auth_login, novaos_auth_status.

Organizations

  • Every token must carry an organization (organization_id). Without it most calls 403, and the CLI says [ORG_CONTEXT_REQUIRED].
  • novaos-cli auth org list / auth org use <org-id> (stored as activeOrganizationId). Env var NOVAOS_ORGANIZATION_ID overrides.

Tools: novaos_org_list, novaos_org_use.

Roles

  • developer: needed for most remote CLI commands (publish, logs, agent list). Client-side gate plus service enforcement.
  • platform-admin: approves reviews, shadow deploys, connector registration. Developers, publisher owners and tenant admins cannot approve; service accounts never can.
  • Org Owner / Tenant admin: manages the org console (service accounts, models, connectors, MCP subscriptions). Org owner is NOT automatically an app admin.

Scopes (the #1 cause of "works for me, fails in the agent")

NovaOS copies the CALLER's scopes into the run's execution token. Whatever the user or service account lacks, the agent lacks.

Need Scope
Start/read runs agent:execute agent:read
Install agents agent:install
MCP tools mcp:tools:* or mcp:tools:<category> (registered category, not display name)
Models llm:model:* or llm:model:<id>
Knowledge read rag:query rag:collections:read
Knowledge write rag:parse rag:ingest rag:collections:write (+ chunk_document persist_artifact seen in apps)
Memory memory:read:<scope>, memory:write:<scope>

Symptoms: MODEL_UNAUTHORIZED (model scope), "RAG scope mismatch" (rag scopes), MCP "category mismatch" (mcp/llm scopes).

User sign-in for apps (SPA, Logto PKCE) should request agent:execute agent:install mcp:tools:* llm:model:* rag:query rag:collections:read for urn:novaos, org-scoped.

Token facts

  • Resource (audience) urn:novaos. Logto M2M tokens are ES384; NovaOS execution tokens are RS256: validators must accept both. Gateway JWKS: <gateway>/.well-known/jwks.json.
  • Every client_credentials request needs resource=urn:novaos AND organization_id, or the gateway returns a silent 403.
  • Refresh tokens rotate on every use: store the new one immediately.
  • Logto end-session page has CSP form-action 'self' (blank page in Chrome): sign out locally and use prompt=login to switch accounts.