NovaOS MCP
Field guide

NovaOS overview and glossary

What NovaOS is, the IDs you will meet, and how this MCP server's tools are organized.

What NovaOS is

NovaOS (Orbitron AI) is a platform to build, publish, govern and run AI agents. Agents are small web services (Python, A2A protocol) packaged as container images. NovaOS hosts them, gives them a governed LLM gateway, MCP tools, a knowledge base (RAG + GraphRAG), memory, a marketplace for installation, service accounts for app backends, metering, approvals and logs.

Typical lifecycle:

  1. Set up a computer (Python 3.12+, Docker, novaos-cli >= 2.2.1).
  2. Sign in to an environment (US staging by default, or FDE US) and pick an organization.
  3. Build an agent with the Python SDK (novaos-agent-sdk, import novaos_client_sdk).
  4. Check it locally (contract tests, lint, agent card), then novaos-cli publish -> review -> platform-admin approval -> ACTIVE.
  5. Install it (marketplace) to get an instance, then TEST IT ON NOVAOS. There is no local testing of NovaOS behavior: the LLM gateway, MCP tools, RAG and the run context exist only inside NovaOS.
  6. Optionally: knowledge base, MCP tool servers, service accounts for backends.

Glossary of IDs (never interchange them)

ID What Where it comes from
Publisher slug Your team's marketplace identity, goes in manifest publisher novaos_publisher_show
Agent ID Catalog id of an agent (stable across versions) publish output, novaos_agent_list
Review ID One publish submission in the review pipeline publish output
Instance ID One installation of an agent for ONE principal (a user or a service account), per environment novaos_instance_install, novaos_instance_list
Run ID One execution on an instance novaos_run_start / novaos_ask_agent
Thread ID Gateway conversation thread (must be created by the gateway) returned by execute
A2A Task ID The agent's own A2A task id (local SDK calls only) Client.send_message
Collection ID A knowledge-base collection (org-wide, shared by all apps) novaos_kb_collection_create
Org (tenant) ID Organization; must be in every token novaos_auth_status

A user can only run instances THEY own; a service account only its own. A personal install is never a substitute for a service-account install.

Environments

Name Label API base Notes
staging US staging https://api.staging.novaos.orbitronai.com Default. IAM https://id.staging.novaos.orbitronai.com, marketplace https://marketplace.staging.novaos.orbitronai.com.
fde FDE US https://api.fde.us.orbitronai.com IAM https://id.fde.us.orbitronai.com, marketplace https://marketplace.fde.us.orbitronai.com.
staging-eu EU staging https://api.stg.eu.orbitronai.com Unverified. IAM https://id.stg.eu.orbitronai.com; some Claude models not deployed
local built into the CLI http://localhost:300x platform developers only

Switch with novaos_env_use {"env":"fde"} or {"env":"staging"}. Service URLs derive from the API base: /gateway, /agent-ops, /mcp-ops, /review, /s2s (RAG), /llm, /s2s/connector.

Hosted or local

  • Hosted: connect the AI app to <server>/mcp (no sign-in) or <server>/mcp/auth (NovaOS sign-in via OAuth). The server never touches the user's computer: steps that need it (installs, project files, Docker publish, novaos-cli) come back as exact commands the AI app runs in its terminal. Needs Node.js 20+ on the computer for those steps.
  • On /mcp, NovaOS actions also run on the computer with the user's novaos-cli login (novaos-cli auth login, via the setup_cli journey).
  • On /mcp/auth, NovaOS actions (instances, runs, tests, knowledge base, conversations, cost) run on the server as the signed-in user. Publishing still runs on the computer.
  • Local: the same server on stdio (novaos-mcp), with direct access to the computer.

How this MCP server is organized

  • guide tools: orientation and knowledge (novaos_start_here, novaos_docs, novaos_explain_error, novaos_ui_guide, novaos_template).
  • workflow tools: resumable journeys (zero_to_hero, setup_machine, build_agent, ship_agent, knowledge_base, connect_backend).
  • molecule tools: one outcome made of several operations (novaos_agent_create, novaos_agent_publish, novaos_ask_agent, novaos_kb_ingest, ...).
  • atom tools: one raw operation (one CLI command or one API call), plus novaos_cli and novaos_api escape hatches.

Set NOVAOS_MCP_PROFILE=beginner to hide atoms. Errors always say WHO is at fault (NovaOS platform, CLI, your input, your setup, auth, capacity) and what to do; NovaOS-side bugs can be drafted with novaos_report_bug.

Official sources