Skip to content
Back to search

vspc-mcp

MCP server for the Veeam Service Provider Console (VSPC) REST API v3: companies, backup servers, jobs and failed sessions across all tenants

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cititec-pty-ltd--vspc-mcp/badge.svg)](/listings/cititec-pty-ltd--vspc-mcp)

HTML

<a href="/listings/cititec-pty-ltd--vspc-mcp"><img src="/api/listings/cititec-pty-ltd--vspc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 93 lines
  1. # VSPC MCP server
  2. An MCP server for the [Veeam Service Provider Console](https://www.veeam.com/service-provider-console.html) (VSPC) REST API v3. VSPC sees every client's Veeam Backup & Replication servers, Veeam Agents and Veeam Backup for Microsoft 365 servers, so Claude can answer questions across all clients in one call, for example "which backups failed in the last 24 hours?". Separately named write tools can start or retry a job and acknowledge or resolve an alarm.
  3. **VCSP vs VSPC.** VCSP (Veeam Cloud Service Provider) is Veeam's partner programme. VSPC is the console a VCSP partner uses to manage its clients' Veeam, and it is what these tools read. Questions about either belong here. In particular, `vspc_get_license_usage` gives the licence usage (points and instances) that is reported to Veeam under the VCSP programme.
  4. It uses the same framework as Cititec's other MCP servers: TypeScript, `@modelcontextprotocol/sdk`, a stdio transport, vitest tests, tsup and a Docker image.
  5. ## The API
  6. - **VSPC 9.1 = REST API 3.6.1**, at `https://<console>:1280/api/v3`. Paths, filters and fields were taken from Veeam's OpenAPI document for 3.6.1 (the one the console serves on its Swagger page).
  7. - **Authentication:** a **Simple REST API key**, sent as `Authorization: Bearer <key>` on every request. No token exchange, and the key does not expire; it works until its user is disabled or deleted. Create it in VSPC under **Configuration > Access Management > REST API Keys** (scope `rest`). Tick read-only unless the write tools are wanted: a read-only key allows GET only.
  8. - **API contract:** every request sends `X-Client-Version: 3.6.1`, so a newer console answers in the 9.1 contract the tools were written for.
  9. - **Collections** are paged with `limit` (max 500) and `offset`. `meta.pagingInfo` gives `total`, `count` and `offset`. Every list tool returns `total`, `count`, `offset` and `nextOffset` when there is more.
  10. - **Filters** are JSON in the query string (`filter=[{"property":"status","operation":"equals","value":"Failed"}]`). Tools build them from typed parameters. No tool takes a free-form path, filter or property name.
  11. - **No session history.** VSPC v3 has no job-session endpoint. Each job carries its **latest** session: result, start, end and failure message. "Failed in the last N hours" therefore means "the latest session failed and ended in the last N hours". A job that failed and then succeeded on retry is not a failure any more. `vspc_failed_jobs_summary` adds VSPC's own session counts for the window (the job-session heatmap), which do include every session.
  12. ## Configuration
  13. | Variable | |
  14. |---|---|
  15. | `VSPC_URL` | The console address, https only, with its port: `https://vspc.example.local:1280`. A trailing `/api/v3` is accepted. |
  16. | `VSPC_API_KEY` | The Simple REST API key. Never logged; removed from every error message. |
  17. | `VSPC_ACCEPT_SELF_SIGNED` | `true` only when the console's certificate is self-signed or not issued for the name in `VSPC_URL`. The connection stays encrypted, but the server is not authenticated, so use this only over a trusted path (VPN). Default `false`. |
  18. | `LOG_LEVEL` | `debug`, `info` (default), `warn`, `error`. Logs go to stderr. Tool arguments and the key are never logged. |
  19. ## Tools
  20. Read tools only send GET requests. Results are trimmed to the useful fields. Company and server UIDs are turned into names, and each response is capped at 60,000 characters. `company` accepts a company's UID or its name (an exact or unique partial match). A job belongs to one company: the company it is assigned to (`mappedOrganizationUid`), or the backup server's owner (`organizationUid`) when it is not assigned. A job on a hosted server shows under, and is filtered by, that one company. It is not listed for the provider that owns the server. A company name is resolved after reading every match (up to 1,000), so an exact match always wins. The organisation and backup server name lists are cached for 5 minutes per console and key (a failed lookup is not cached). Secrets in VSPC responses, such as a company's owner credentials, are never returned.
  21. | Tool | VSPC endpoint(s) |
  22. |------|------------------|
  23. | `vspc_about` | `GET /about` |
  24. | `vspc_list_companies` / `vspc_get_company` | `GET /organizations/companies[/{uid}]` |
  25. | `vspc_list_backup_servers` | `GET /infrastructure/backupServers` (status, version with patch, role) |
  26. | `vspc_list_jobs` | `GET /infrastructure/backupServers[/{uid}]/jobs`, filtered by company, server, latest result, name, enabled |
  27. | `vspc_list_agent_jobs` | `GET /infrastructure/backupAgents/jobs` (Veeam Agent jobs and backup policies, with computer names) |
  28. | `vspc_list_failed_jobs` | All three job lists, filtered on the latest result (Failed, optionally Warning) and paged through: every failure in the last N hours across all companies, newest first, with the failure reason |
  29. | `vspc_failed_jobs_summary` | As above, one row per job. Retries of a job, and an agent job failing on several computers of one company, are folded together. Also gives counts per company and the session counts from `GET /infrastructure/jobSessionHeatmap/` |
  30. | `vspc_list_alarms` | `GET /alarms/active` (Error and Warning by default, newest first), with alarm names from `GET /alarms/templates`. `hours` is sent to VSPC as a `lastActivation.time` filter, so paging is exact. If the console refuses that filter, the window is applied here instead: `timeFilter: "client"` with `count`, `pageCountUnfiltered`, and no `nextOffset` once the page reaches older alarms |
  31. | `vspc_list_protected_vms` | `GET /protectedWorkloads/virtualMachines` (`oldest_first` finds stale backups) |
  32. | `vspc_list_backup_policies` | `GET /configuration/backupPolicies` |
  33. | `vspc_get_license_usage` | `GET /licensing/usage/organizations`: used, new and rental units and counts per workload (with the per-platform split), and totals per workload and unit type |
  34. | `vspc_get_console_license` | `GET /licensing/console` |
  35. Job sources in the failure tools:
  36. - `backup_server`: Veeam Backup & Replication jobs, including agent jobs managed by VBR.
  37. - `agent`: Veeam Agents managed by VSPC.
  38. - `vb365`: Veeam Backup for Microsoft 365 jobs.
  39. A failure count is never shown as a clean zero when data is missing:
  40. - If no source can be read (for example, the console is unreachable), the tool returns an error giving each source's reason. A rate-limit wait is kept, as `rate_limited`.
  41. - If some sources fail, or one is cut short at its cap, the result starts with `complete: false` and a `warning`: the counts are a lower bound, and zero does not mean no failures. The result lists `sourceErrors` and `partialSources`.
  42. - If VSPC's session counts cannot be read, the summary returns `sessionCounts: null` and gives the reason.
  43. - A name lookup or count that failed is listed in `lookupErrors`, so a refused request (403) is not mistaken for a passing glitch. It gives what was being looked up, the error text (method and path only, never the key or query string), the HTTP status, and for a 429 `rateLimited` and `retryAfterSeconds`. Rows still show UIDs where the names are missing. `sourceErrors` use the same form. The same failure on many items, such as one agent-name GET per agent refused with 403, is listed once with a `count`. Agents beyond the 40 named per call are listed too: they show their UID. When the alarm time filter falls back, `timeFilterFallback` gives the reason.
  44. ### Write tools
  45. Each write tool makes exactly one POST to a fixed endpoint, with a validated UID and no lookups first. On the Cititec MCP host, the proposal an administrator approves is exactly what is sent. Writes are **never retried**. They need a key that is not read-only.
  46. **Idempotency.** VSPC treats `X-Request-id` as an idempotency key for 5 minutes. A write's id is derived from the tool name and its validated arguments (canonical JSON, keys sorted; SHA-256 shown as a version 8 UUID). If an identical write is sent again within 5 minutes, VSPC runs it once. Examples: a response lost on the network and sent again, or the same proposal approved twice. A different job, alarm or comment gets a different id. So does the same write more than 5 minutes later. Starting the same job twice on purpose within 5 minutes therefore runs it once. Reads send no request id.
  47. | Tool | VSPC endpoint |
  48. |------|---------------|
  49. | `vspc_start_job` | `POST /infrastructure/backupServers/jobs/{jobUid}/start` |
  50. | `vspc_retry_job` | `POST /infrastructure/backupServers/jobs/{jobUid}/retry` |
  51. | `vspc_acknowledge_alarm` | `POST /alarms/active/{alarmUid}/acknowledge?comment=...&resolveOnClients=...` |
  52. | `vspc_resolve_alarm` | `POST /alarms/active/{alarmUid}/resolve?comment=...&resolveOnClients=...` |
  53. ## Rate limits (Cititec fleet 429 policy)
  54. VSPC throttles with HTTP 429 and gives the wait either in a `Retry-After` header or in a `retryAfter` property in the body.
  55. - **Reads (GET):** retried once if the wait is 10 s or less.
  56. - **Longer or missing wait:** the tool returns at once with a structured error: `structuredContent: { "error": "rate_limited", "retryAfterSeconds": N }`, plus the text `Try again in N s`.
  57. - **Writes:** never retried.
  58. ## Running it
  59. ```bash
  60. npm ci
  61. npm run build
  62. VSPC_URL=https://vspc.example.local:1280 VSPC_API_KEY=... node dist/index.js # stdio
  63. npm test
  64. ```
  65. The Docker image is `ghcr.io/cititec-pty-ltd/vspc-mcp`. It is published by the *Cititec release* workflow (semantic-release) on every release commit to `main`. On the Cititec MCP host, each connection gets its own container (`docker run --rm -i`) with the service's env file.
  66. ## Licence
  67. Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.