NovaOS MCP
Reference

All 80 tools

Four levels: guide, workflow, molecule, atom. Tools marked "changes state" ask before acting. Set NOVAOS_MCP_PROFILE=beginner to hide atoms.

ToolDomainLevelWhat it does
novaos_templateagentguideLists or shows proven code templates: agent-python (server.py dispatcher, novaos_helpers.py with LLM gateway/progress/heartbeat/RAG/MCP/returned writes, manifest, Dockerfile, tests), backend-python / backend-typescript (service-account client with stream resume and capacity handling), mcp-python (read-named MCP server), eval (suite).
novaos_agent_createagentmolecule changes stateCreates a ready-to-publish Python A2A agent from a battle-tested template: one dispatcher skill (ping/chat/models/search), LLM gateway calls with disable_fallbacks + served-model check + cost, heartbeat progress, RAG search, returned-writes helper, read-only-FS Dockerfile, contract tests, and an AGENTS.md for AI assistants.
novaos_agent_lintagentmoleculeStatic check of an agent project against every known NovaOS publish/run trap: manifest schema, base_image label, publisher placeholder, version drift with code, multi-skill routing, memory prefetch, card drift (manifest vs @agent.skill), lowercase SkillResult statuses, ctx.tools.llm, wrong import name, LLM calls without disable_fallbacks, MCPClient misuse, RAG query, old vendored SDK, TestPyPI, Dockerfile root/port, .dockerignore hiding prompts, tracked .env.
novaos_agent_cardagentatomRuns the SDK's agent-card capture (what publish does) to prove the module loads and the declared skills match.
novaos_cli_initagentatom changes stateRuns `novaos-cli init` exactly (raw scaffold).
novaos_manifest_validateagentatomRuns `novaos-cli manifest validate --json` (offline, the same validator publish uses) for an agent manifest, or `mcp validate` for an MCP server manifest.
novaos_auth_loginauthmolecule changes stateSigns in to NovaOS through novaos-cli: opens the browser sign-in page (OAuth + PKCE), waits for it to finish (up to ~2 minutes), then reports the identity, org and roles.
novaos_env_setupauthmolecule changes stateRegisters an environment with novaos-cli (env add) from a known preset (staging = US staging, fde = FDE US, staging-eu) or from URLs you give, optionally makes it active for both the CLI and this server.
novaos_auth_statusauthatomChecks sign-in for an environment without changing anything: subject, organization, roles, token lifetime and missing recommended scopes.
novaos_env_listauthatomLists NovaOS environments known to novaos-cli (~/.novaos/environments.json) and this server's presets, marks the active one, and flags the CLI trap where an unknown env name silently falls back to 'local'.
novaos_env_showauthatomShows every resolved service URL (gateway, agent-ops, mcp-ops, review, IAM, marketplace, S2S/RAG, LLM gateway) for an environment.
novaos_env_useauthatom changes stateMakes an environment active for this server and for novaos-cli.
novaos_org_listauthatomLists the organizations the signed-in user belongs to (novaos-cli auth org list).
novaos_org_useauthatom changes stateMakes an organization active for the CLI and this server (org-scoped token).
novaos_publisher_showauthatomShows the marketplace publisher slug used in manifest 'publisher' (novaos-cli publisher show).
novaos_conversation_getchatatomReads one platform conversation and its messages (GET /api/v1/conversations/{id} and /messages).
novaos_conversation_historychatatomShows the locally kept history (and gateway thread id) of a conversation created by novaos_ask_agent {conversation}.
novaos_conversation_updatechatatom changes stateUpdates a platform conversation (PATCH /api/v1/conversations/{id}): title, context_summary, token_budget, context_strategy.
novaos_conversationschatatomLists platform conversations (GET gateway /api/v1/conversations, filter by instance_id and status active|archived|deleted).
novaos_hitl_decidechatatom changes stateSends a native human-in-the-loop decision for a run waiting on approval (WAITING_USER / WAITING_AUTH): POST /api/v1/conversations/{thread_id}/hitl {approved}.
novaos_error_catalogdebugguideLists the catalog of known NovaOS errors, codes and known platform bugs this server recognizes, with fixes.
novaos_explain_errordebugguideExplains any NovaOS error text (from the CLI, SDK traceback, HTTP response, run event, UI message or JSON-RPC code): who is at fault (NovaOS platform, CLI, your input, your setup, auth, capacity), the likely cause, the fix, and whether it is a known NovaOS bug.
novaos_job_statusdebugguideShows the state and last log lines of a background job (installs, builds, publish, ingest).
novaos_report_bugdebugguideDrafts a ready-to-file bug report for the NovaOS team from an error (title, environment, versions, exact request, request/run ids, expected vs actual, repro steps, workaround).
novaos_run_diagnosedebugmoleculeExplains why a run failed or hung: reads the run, its events, the platform trace (novaos-cli debug trace) and, if agent_id is given, the agent logs for that run; classifies the failure (agent code vs platform capacity vs auth/scope vs MCP refusal vs stream cut) and says what to do.
novaos_agent_logsdebugatomFetches a deployed agent's logs (novaos-cli agent logs).
novaos_kb_collection_createknowledgemolecule changes stateCreates a RAG collection with the right embedding model for the environment's region (US text-embedding-3-small/1536, EU text-embedding-004/768; a wrong model fails only later at ingest), idempotently (client_request_id), and saves its id under a local name.
novaos_kb_graphknowledgemolecule changes stateGraphRAG on a collection: action=build starts building the knowledge graph (a write; takes minutes), status shows progress, local asks a relationship question about specific entities (graph_query), global asks a corpus-wide summary question (global_query).
novaos_kb_ingestknowledgemolecule changes stateIngests local files into a collection the robust way: checks size (7 MiB practical cap), skips files already ingested (sha256), picks a parser from live capabilities (docling / pymupdf / OCR / xlsx / anydoc), parses once with a persisted artifact, ingests from the parse with sensible chunking, polls jobs, fixes the duplicate-upload bug, and records document ids.
novaos_kb_searchknowledgemoleculeHybrid (vector + keyword) search over a collection with the NovaOS planner OFF (faster, predictable), deduped hits, optional document filter.
novaos_kb_capabilitiesknowledgeatomLists the RAG parsers (sync and async: text, csv, html, pymupdf, pdfplumber, docx, xlsx, docling, surya OCR, anydoc ...) and chunking strategies this environment offers (GET s2s /rag/capabilities).
novaos_kb_collection_deleteknowledgeatom destructivePermanently deletes a RAG collection and its documents.
novaos_kb_collectionsknowledgeatomLists RAG collections visible in the org (they are org-wide and shared across apps) plus the names/ids saved on this machine.
novaos_kb_documentsknowledgeatomLists documents in a collection with chunk counts and content hashes.
novaos_kb_parseknowledgeatomParses one local file with a chosen parser and returns text/tables/page count, without adding it to a collection.
novaos_kb_toolknowledgeatom changes stateCalls one NovaOS RAG tool over S2S JSON-RPC with exact arguments.
novaos_llm_modelsllmatomLists the model directory of the NovaOS LLM gateway (GET gateway /api/v1/llm/models; developer or platform-admin role).
novaos_instance_installmarketplacemolecule changes stateInstalls an agent for the caller (POST marketplace /api/instances, adapter_type A2A, CSRF header) and waits until READY.
novaos_catalog_searchmarketplaceatomLists agents in the marketplace catalog (GET marketplace /api/agents), optionally filtered by text.
novaos_instance_listmarketplaceatomLists installed agent instances visible to the caller (GET gateway /api/v1/instances): instance_id, agent, version, status.
novaos_mcp_publishmcpmolecule changes statePublishes an MCP tool server (novaos-cli mcp publish): validates, checks names, reads secrets from the git-ignored .env next to the manifest, builds and pushes, submits for review.
novaos_mcp_server_createmcpmolecule changes stateCreates a Python MCP tool server (FastMCP, streamable HTTP :3000) that agents call as <publisher>.<name>.<tool>: read-named example tools, tenant taken from trusted gateway headers, non-root Dockerfile with a working health check (the CLI template's curl check fails on python:slim), and a test that enforces NovaOS's read/write naming rules.
novaos_mcp_name_checkmcpatomClassifies MCP tool names exactly like NovaOS does (by leaf name, fail-closed).
novaos_cost_estimatemeteringguideEstimates the cost of model calls from token counts with list prices (USD per 1M tokens).
novaos_usagemeteringatomReads NovaOS platform cost for your org (marketplace admin cost API): summary (total, by category, top agents and plugins/models), breakdown (group_by agent/operation_type/plugin), records, per-agent usage, a service account's usage, or one operation, over a period (7d, 30d, YYYY-MM, all).
novaos_agent_publishpublishmolecule changes statePublishes an agent version: pre-flight (Docker running, signed in, lint errors, placeholder publisher), then `novaos-cli publish` (build, card capture, push, submit for review) as a background job.
novaos_wait_for_approvalpublishmoleculePolls a review until it is ACTIVE or REJECTED (up to ~45 s per call).
novaos_agent_listpublishatomLists the publisher's agents with agent ids (marketplace developer API via novaos-cli agent list).
novaos_agent_versionspublishatomLists published versions of an agent (novaos-cli release list --agent <agent-id>).
novaos_publish_historypublishatomLists agents and MCP servers published through this server (env, version, review id, agent id).
novaos_publish_statuspublishatomShows the review pipeline status of a publish (PENDING_SCAN, SCANNING, PENDING_REVIEW, APPROVED, ACTIVE, REJECTED, ROLLED_BACK).
novaos_apirawatom changes stateRaw authenticated HTTP call to a NovaOS service (gateway, agentOps, mcpOps, review, marketplace, s2s, llm, connectorHost, metering, iam) with errors translated.
novaos_clirawatom changes stateRuns a novaos-cli command with --env set explicitly and returns its output (JSON when --json).
novaos_ask_agentrunsmolecule changes stateOne call to talk to a deployed agent: finds your instance (by instance_id, or by agent name among your instances), starts a run and waits up to ~45 s for the answer (call novaos_run_wait if still running).
novaos_run_waitrunsmoleculeFollows a run until it finishes (stream with Last-Event-ID resume, then polling) within ~45 s per call, and returns the answer, progress, error and cost.
novaos_run_eventsrunsatomReads the stored events of a run (GET /api/v1/runs/{id}/events?after=) and summarizes them: answer, progress labels, error, usage, cold/warm start.
novaos_run_getrunsatomReads one run (GET gateway /api/v1/runs/{id}): status, timestamps, error.
novaos_run_startrunsatom changes stateStarts one run on an instance (POST gateway /api/v1/execute) and returns run_id + thread_id immediately.
novaos_sa_setup_guideservice-accountguideStep-by-step (with browser steps) to create a NovaOS service account for a backend app: create the SA and its credential in the Organization Console, grant scopes/roles and tool grants, store the secret locally, install the agent FOR the SA (its own instance id), test a run, and wire your backend.
novaos_app_integration_codeservice-accountmolecule changes stateWrites a production-grade NovaOS client module into your backend: service-account token mint + cache (resource + organization_id), execute with idempotency, SSE stream with Last-Event-ID resume, poll-and-replay recovery after cuts (never re-run), 429 capacity backoff, pod-quota detection, gateway thread mapping with THREAD_NOT_FOUND retry, and friendly errors.
novaos_sa_credentials_fileservice-accountmolecule changes stateCreates a private credentials file (~/.novaos-mcp/secrets/<ref>.json, mode 600) with blanks for client_id, client_secret and org_id, and opens it in a text editor so the USER pastes the secret there.
novaos_sa_token_testservice-accountmoleculeMints a client_credentials token for a stored service account (resource urn:novaos + organization_id, without which NovaOS silently 403s), and reports org, granted scopes and what is missing for running agents, MCP tools, models, installs and RAG.
novaos_sa_listservice-accountatomLists service-account credential refs stored on this machine (names only, never secrets) and which is the default.
novaos_install_plansetupguideReturns the exact install steps for this operating system for one or more components (brew, python, node, git, docker, wsl, novaos-cli).
novaos_doctorsetupmoleculeChecks everything NovaOS development needs on this computer (Python 3.12+, Node, Git, Docker running, novaos-cli version, the SDK in a project venv) and says what is missing, why it matters, and how to fix it.
novaos_installsetupmolecule changes stateInstalls one component (python, node, git, docker, novaos-cli, or upgrades novaos-cli) using the OS package manager, as a background job.
novaos_python_envsetupmolecule changes stateCreates (or repairs) a Python virtual environment in <project_dir>/.venv with Python 3.12+ and installs the pinned public SDK (novaos-agent-sdk) from public PyPI, plus optional local-server deps (fastapi, uvicorn, pydantic).
novaos_sdk_versionssetupatomLists published versions of the Python SDK (PyPI) and novaos-cli (npm) and the recommended ones, so you can pin or upgrade deliberately.
novaos_docsstartguideSearches the bundled NovaOS field guides (official docs plus lessons learned building AssetNova and other apps): setup, agents, manifest, CLI, knowledge/RAG, publish and approvals, instances, service accounts, runs and streaming, chat, LLM gateway, metering, errors.
novaos_start_herestartguideOrientation for anyone (including non-technical users): checks this computer, the NovaOS environment and sign-in, the current project and saved progress, then recommends the single best next step and the guided journey to follow.
novaos_tool_indexstartguideLists every tool in this server grouped by domain and tier (guide, workflow, molecule, atom).
novaos_ui_guidestartguideReturns the URL and exact clicks for NovaOS web UI tasks (for the AI client's browser tool or the user): approvals, publishes, publisher_profile, install_agent, install_for_service_account, service_accounts, rotate_secret, mcp_servers, external_connector, agent_logs, spending, rate_limits, models_connectors.
novaos_workflow_continuestartworkflow changes stateContinues a journey.
novaos_workflow_liststartworkflowLists the guided, resumable NovaOS journeys (zero_to_hero, build_agent, ship_agent, knowledge_base, service_account_app, ...) with what each achieves and its steps.
novaos_workflow_retrystartworkflow changes stateResets the failed or stuck current step of a journey and runs it again.
novaos_workflow_startstartworkflow changes stateStarts a resumable journey and immediately runs its first steps.
novaos_workflow_statusstartworkflowShows the step checklist and saved context of a journey run; without run_id lists recent runs.
novaos_test_deployedtestingmolecule changes stateTests the PUBLISHED and INSTALLED agent through NovaOS: each case starts a real run (execute + stream) and checks status and answer (contains, exact_match, regex).
novaos_agent_testtestingatomRuns the agent's contract tests (pytest in .venv): version sync, one skill, operations enum, statuses, input parsing.
novaos_eval_platformtestingatom changes stateLists platform eval runs for an agent (novaos-cli eval list) or starts a platform suite run (eval run; may be unavailable on some envs).