NOVA CLI reference 0.5.0 GitHub
  1. nova

nova mcp

EXPERIMENTAL: Start an MCP server for the selected instance

Synopsis

EXPERIMENTAL: Start an MCP server (stdio) with curated tools for the selected instance.

Toolsets served by default (mostly reads): instances (only when not pinned), context, cells, controllers, virtual-controllers, motion-group-models, system, apps, diagnosis, guides, kinematics, datasets Opt-in with --toolsets (e.g. --toolsets default,planning,motion or --toolsets all): planning, stores, motion, programs, maintenance

The tools follow the roadmap of the instance MCP service that is planned for a NOVA release; until it ships, 'nova mcp' serves them locally and calls the NOVA v2 API of the instance with your 'nova' login.

Guard rails (not a safety function):

  • Motion, I/O writes and mode changes only run on virtual controllers; on a physical controller they are refused with APPROVAL_REQUIRED, a human runs them through an app or the NOVA UI.
  • Deleting a cell, restoring a backup and updating NOVA ask you through the MCP client (elicitation); clients that can't ask get APPROVAL_REQUIRED.
  • --read-only drops every tool that changes anything.

Downloads (diagnosis packages, backups) are saved to --download-dir.

The server starts on the selected instance ('nova instance select <name>'). The agent can switch it for the session with list_instances and use_instance; that never changes the selection in the config. Pinned with --instance <name> or NOVA_INSTANCE (e.g. in the "env" of the MCP client config), the server stays on that instance and doesn't offer those tools. Cloud instances need a 'nova login'; the login is refreshed automatically while the server runs.

Example for Claude Code ('.mcp.json') or Cursor ('.cursor/mcp.json'):

{ "mcpServers": { "nova": { "command": "nova", "args": ["mcp", "--read-only"], "env": { "NOVA_INSTANCE": "my-instance" } } } }

Diagnostics go to stderr; stdout carries only the MCP protocol.

nova mcp [flags]

Examples

  nova mcp
  nova mcp --instance my-instance --read-only
  nova mcp --toolsets default,planning,motion
  nova mcp --toolsets all --download-dir ./nova-downloads

Options

      --download-dir string   where tools save files such as diagnosis packages and backups; must be private to you (default: <user cache dir>/nova/mcp-downloads)
  -h, --help                  help for mcp
      --read-only             serve only tools that don't change the instance
      --toolsets strings      comma-separated toolsets to serve, 'default', 'all' or any of: instances, context, cells, controllers, virtual-controllers, motion-group-models, system, apps, diagnosis, guides, kinematics, datasets, planning, stores, motion, programs, maintenance

Options inherited from parent commands

      --debug                      Write diagnostic output to stderr: HTTP requests and responses, external commands, the resolved instance. Known secrets are redacted, but bodies (app environments, kubeconfigs) can still contain some: don't share the output unreviewed (env: NOVA_DEBUG=1)
      --env string                 (Wandelbots internal) Portal environment for this invocation: prod, stg or dev (default: the environment of the cloud instance, else of the last 'nova login'; env: NOVA_ENV)
      --insecure-skip-tls-verify   If true, the server's certificate will not be checked for validity (disables TLS verification for all requests)
      --instance string            Name of the instance to work against for this invocation (overrides the selected instance; env: NOVA_INSTANCE)

SEE ALSO

  • nova - CLI for interacting with Wandelbots NOVA OS