NovaBACKUP Management Server MCP

An MCP (Model Context Protocol) server that lets MSPs manage their NovaBACKUP Management Server tenants from Claude Desktop, Claude Code, or any other MCP-compatible client.

It federates across multiple Management Servers — you can ask things like "show me every failing job in the last 24 hours across all my customers" without caring which physical instance hosts which customer. Tenant- and permission-scoped: every MSP user authenticates with their own CMon credentials, and the MCP can only see what that user is allowed to see.

How auth works

Each MSP user logs in once via a small companion CLI (novabackup-mcp login). It walks them through entering the Management Server URL, username, and password, verifies the credentials against /api/Account/Authenticate, and writes them to ~/.novabackup-mcp/credentials.json (mode 0600 on Unix; restricted to the user profile on Windows).

After that, every time Claude Desktop spawns the MCP it auto-connects all configured servers, refreshes JWTs as they expire, and tools just work. No credentials in chat. No service accounts. No mcpServers.env.PASSWORD in your config file.

If you ever need to authenticate ad-hoc inside a Claude conversation — for example, a server that isn't in your saved credentials — the connect_server tool can either elicit credentials out-of-band (when the client supports MCP elicitation) or take them as explicit arguments (less ideal, since they appear in tool-call history).

Quick start

1. One-time login

In a terminal:

npx -y @novabackup/management-server-mcp login

You'll be prompted for:

• Server ID (a short label, e.g. cmc-test)
• Friendly label
• Management Server URL (include the virtual directory if hosted, e.g. https://cmc.novabackup.com/managementserver)
• CMon username
• CMon password

The CLI verifies the credentials work, then saves them. Re-run it to add another server or update an entry.

You can list, test, or remove saved entries:

npx -y @novabackup/management-server-mcp list
npx -y @novabackup/management-server-mcp test            # tests every saved entry
npx -y @novabackup/management-server-mcp test cmc-test   # tests one
npx -y @novabackup/management-server-mcp logout cmc-test

2. Wire into Claude Desktop

Add this to claude_desktop_config.json (typically at %APPDATA%\Claude\claude_desktop_config.json on Windows). If the file already has an mcpServers block, merge the entry in — don't overwrite:

{
  "mcpServers": {
    "novabackup": {
      "command": "npx",
      "args": ["-y", "@novabackup/management-server-mcp"]
    }
  }
}

Fully quit Claude Desktop (Settings → Quit) and reopen.

3. Try it

In Claude Desktop, in a new conversation:

"Use the novabackup MCP. Show me agent health for the last 24 hours across all my servers."

Expected: Claude calls system_info, sees the saved server is already connected via auto-connect, then runs list_agents and get_job_history_summary and produces a summary.

Configuration

| Env var | Default | Purpose | |---|---|---| | MCP_CREDENTIALS_FILE | ~/.novabackup-mcp/credentials.json | Path to the credentials file (set this if you want a different location) | | MCP_SERVERS_FILE | (none) | Optional path to a servers.json file with non-secret presets — only useful when you don't want to use the credentials file | | MCP_ALLOW_WRITES | false | Set to true to register write/destructive tools (when implemented) | | MCP_ALLOWED_TENANT_IDS | (none) | CSV of tenant Guids; if set, write calls outside this list fail closed | | MCP_LOG_LEVEL | info | pino log level | | MCP_OPERATION_TIMEOUT_SECONDS | 60 | Per-tool-call timeout | | MCP_FANOUT_CONCURRENCY | 5 | Max parallel server requests during fan-out |

Tool surface

Every list-tool output includes server_id and tenant_id per item plus a _meta block describing fan-out coverage so Claude can detect partial failures.

Orientation

• system_info — first call to make. Returns mode, the connected MCP client's capabilities (notably supports_elicitation), saved presets, currently-connected servers
• list_servers, server_health

Connection (rarely needed if you used login)

• connect_server — connect ad-hoc. Prefers MCP elicitation; falls back to explicit args (base_url, username, password)
• disconnect_server — clear creds + JWT for a single server

Read-only data tools (fan out across connected servers when no server_id is given)

• Agents: list_agents, get_agent, list_agent_devices
• Cloud Storage Accounts: list_cloud_storage_accounts, get_cloud_storage_account
• Storage Servers: list_storage_servers, get_storage_server
• Groups: list_groups, get_group_hierarchy
• Backup Jobs: list_jobs_for_agent, get_job, list_backup_sources
• Job History: list_job_history, get_job_history_summary
• Users: list_users, get_user

Phase 2 (gated behind MCP_ALLOW_WRITES=true, not yet implemented): CSA CRUD, job CRUD + start/stop, validation dry-run.

Prompts

Four canned MSP-workflow prompts ship with the MCP — they appear in Claude Desktop's prompt picker:

• diagnose_failing_jobs (window: 24h/7d/30d)
• audit_cloud_storage_usage
• summarize_agent_health
• find_stale_agents (days: 7+)

Security posture

• Credentials live in ~/.novabackup-mcp/credentials.json with file mode 0600 on Unix. On Windows the file is in the user profile, which Windows already restricts to the owner via NTFS ACLs.
• The credentials file is plaintext — same posture as ~/.aws/credentials, ~/.npmrc auth tokens, ~/.docker/config.json. If you need stronger protection (OS keychain integration), open an issue.
• Passwords are read from disk into memory at MCP startup, used to obtain a JWT, and held in process memory so the JWT can be silently refreshed when it expires. Memory is wiped on process exit.
• No credentials are logged. The structured logger redacts any field whose name matches password|secret|token|authorization|twoFactorCode.
• Each MSP user runs their own MCP instance with their own credentials. There is no shared service account; the JWT issued by the Management Server reflects the user's role permissions and accessible tenants.

Development

git clone https://github.com/NovaStor/management-server-mcp
cd management-server-mcp
npm install
npm run generate:client       # fetches swagger.json (default: cmc.novabackup.com) and generates a typed client
npm run typecheck             # tsc --noEmit
npm run test                  # vitest (full suite)
npm run build                 # esbuild bundle to dist/index.js

To exercise the MCP end-to-end against a real Management Server:

MCP_SMOKE_USERNAME=your-cmon-user \
MCP_SMOKE_PASSWORD='your-cmon-password' \
MCP_SMOKE_SERVER_ID=cmc-test \
node scripts/e2e-smoke-autoconnect.mjs

License

MIT — see LICENSE.