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