vsp360-mcp

An MCP server for the Hitachi VSP 360 1.4 REST API, built from the Platform OpenAPI spec spec/Platform-vsp360-openapi.yaml. It gives Claude (or any other MCP client) access to all 264 API operations. The token endpoint is excluded because the server handles authentication itself.

How it exposes the API

The spec is too large to load as 264 separate tools: their schemas alone come to about 400 KB. The server therefore always provides three discovery tools:

For the areas you use most, set VSP360_TOOLSETS to add direct tools: one tool per operation, each with a full input schema. For example:

VSP360_TOOLSETS="Device Registry,Platform Alerts,VSP 360 Cluster Health"

How vsp360_list_operations finds operations

A search goes through three steps. Only the first one ranks; the other two add advice to the ranked list.

1. BM25 ranking picks and orders the operations.
2. A confidence rating (HIGH, MEDIUM or LOW) says how far to trust the top result.
3. An optional learned hint suggests what to do next. It is off unless VSP360_DECISION_HINT is set.

1. BM25 ranking

A query is ranked with BM25 over each operation’s ID, summary, tag, path, description and a set of example questions (spec/examples.json), so plain-language requests work (“volumes with no host path”, “silence alerts”). The ranking has six refinements:

• Fields are weighted: words in the summary and ID count more than words in the description.
• camelCase is split and light stemming is applied.
• Storage vocabulary is mapped to API terms, for example volume → ldev, LDAP → directories, ESXi → hypervisor.
• Verbs decide intent: “list” and “show” favour read operations, while “delete”, “start” and “register” favour write operations.
• List-style requests prefer collection endpoints over {id} endpoints.
• Example questions bridge operator wording and API wording: each operation has a few questions an operator might ask, such as “take a snapshot now outside the schedule” for protectionTriggerPolicy. Set VSP360_EXAMPLES to another file to use your own, or to an empty string to turn them off.

2. Confidence rating

Each result set carries a confidence of HIGH, MEDIUM or LOW, based on how far the top hit leads the next and how much of the request’s own wording it matches. The rating comes with advice: call the top result, check its description, or describe the top two or three. When a LOW or MEDIUM result looks like a performance or topology question, the response points to analyticsRunQuery.

3. Learned hint (optional)

With VSP360_DECISION_HINT=true, a line under the results suggests what to do with them: call the top operation, compare the top few, answer with Analytics, or search again. It comes from a small model in spec/decision-model.json, trained on logged searches (see Improving search). It never changes the ranking. With ab, it is shown in a random half of server sessions so the two can be compared.

Analytics (MQL) field reference

The spec documents the Analytics query endpoint but not what it can query. Describing analyticsRunQuery therefore adds an mqlReference: MQL usage notes, the attributes and relations of the most-used resource types (raidStorage, raidPool, raidLdev, raidPort, raidHG, raidLU, raidPortWWN, raidPair, the host, fabric and VMware types), and the names of the other 38 types. Describing it with resourceType (for example raidPool) returns one type’s full attribute list. The block, file and object types come from the VSP 360 Metrics Reference Guide; the host, fabric and VMware types were found on a live system and may be incomplete. The reference lives in spec/analytics-fields.json (VSP360_ANALYTICS_FIELDS points to another file).

Measuring search

All user questions live in tests/user-queries.md: regression prompts, labelled questions for evaluation and training, and batch questions for data collection.

npm test builds the server, runs the unit tests in tests/unit/ (the HTTP client against a mock server, the spec loader, and the MCP server end to end, including the read-only block) and then the search evaluation, which fails if any score drops below its threshold. npm run eval scores the search against 83 labelled development requests (45 held out from tuning) and the 119 labelled user questions in tests/user-queries.md (79 held out); EXAMPLES=0 npm run eval measures it without the example questions.

Safety: read-only by default

By default only GET operations are allowed, plus a few POST operations that only query or validate:

• analytics query
• inventory filter query
• authorization check
• user capabilities
• CSV validation
• upgrade version validation
• directory connection test

All other operations are refused, and direct tools are not created for them. These include device registration and deletion, orchestration workflows (volume allocation, expansion, GAD), user and group changes, certificates, upgrades and notifications. To allow them, set VSP360_ALLOW_WRITES=true. DELETE tools are marked destructiveHint, so Claude asks for confirmation before running them.

Reads that return secrets. One read, vsp360GetServiceAccountSecret, returns a service account’s live client secret, which would then become part of the conversation. Every other read masks secrets. That read is refused, whether or not writes are allowed, unless VSP360_ALLOW_SECRET_READS=true.

Local files. Claude chooses save_to and upload paths, so text it reads from the API could try to steer them. save_to therefore only writes inside VSP360_DOWNLOAD_DIR and never overwrites a file (set VSP360_SAVE_ANYWHERE=true to lift the folder rule). Uploads refuse hidden files and folders such as ~/.ssh or .env; set VSP360_UPLOAD_DIR to allow uploads only from one folder.

Features

• Auth: Gets an OAuth2 client_credentials token from POST /api/v1/vsp360/auth/token. It reuses the token until shortly before it expires and fetches a new one automatically after a 401.
• Pagination: Use limit and offset (at most 100 per page), or set all_pages: true to follow the RFC 8288 next links. max_pages caps the number of pages and defaults to 20. The Content-Range and Link headers are included in each result. If a later page is not JSON (for example a gateway error page), the pages before it are kept and a note says where it stopped.
• Downloads: Binary responses are streamed to VSP360_DOWNLOAD_DIR, so large bundles never sit in memory, and the file path is returned. These include diagnostic bundles (.tar.gz), CSR ZIPs and billing reports. A name the server already used gets a numbered suffix. Any call can also pass save_to: "report.json" (a file name or a path inside the download folder); with all_pages, every page is saved.
• Uploads: Multipart operations take local file paths, for example files: {"file": "~/devices.csv"}. This applies to installing a TLS certificate, validating a bulk-registration CSV, and uploading an upgrade package. Files are streamed from disk, so 20 GB .zst upgrade packages don’t need to fit in memory. Hidden files are refused (see Safety).
• TLS: Use VSP360_CA_CERT for a private CA. Use VSP360_INSECURE_TLS=true only for lab systems with self-signed certificates.
• Large responses: Responses longer than VSP360_MAX_RESPONSE_CHARS are truncated, with a note telling Claude how to narrow the request.

Improving search: logging and the learned hint

These tools collect data on how Claude uses search results and train the learned hint from it. None of them is needed to use the server.

Decision log

Set VSP360_DECISION_LOG to a file path to record, locally, how search results are used:

• For each search: the query and, if Claude passes it, the user’s own request that led to the search (the request argument, offered only while the log is on and never used for ranking); the confidence rating and the signals behind it (lead, coverage, intent, the analytics hint), and the ranked operationIds.
• For each describe or call: the operationId, its rank in the most recent search if it started within VSP360_DECISION_LINK_SECONDS of it (otherwise it is logged as unlinked), the seconds since that search, the HTTP status and the duration. Calls also record the names of the arguments used.

Argument values, request and response bodies, headers and credentials are never logged. The query text is logged as typed, so treat the file as you would chat history.

Collection mode

With VSP360_DECISION_COLLECT=true (and the log on), the server makes every question produce a labelled search: a search with query must also carry request, and vsp360_call_operation (or a direct tool) is refused unless the operation appeared in a search result within the last VSP360_DECISION_COLLECT_SECONDS (default 600). Refusals are logged. Claude is slower in this mode, so turn it on for a data-collection period and off afterwards; turning writes off (VSP360_ALLOW_WRITES unset) for the period is also a good idea.

Batch collection

npm run collect-batch -- --part N sends the questions in one part of tests/user-queries.md to Claude through the API, one fresh conversation per question, with its own vsp360 server running read-only in collection mode. It needs an Anthropic API key (ANTHROPIC_API_KEY; usage is billed), skips the held-out test questions, resumes where it stopped, and writes to reports/decisions-batch.jsonl (decisions) and reports/batch-answers.jsonl (answers, which contain live VSP 360 data). --dry-run lists what would run; --limit N, --only 1,2, --model and --effort adjust a run.

Training the learned hint

spec/decision-model.json is a small learned model (npm run train-decision -- --write rebuilds it) that suggests what to do with a search result: call the top operation, compare the top few, use Analytics, or search again. With VSP360_DECISION_HINT=true the suggestion is added under the search results; with ab it is shown in a random half of server sessions, so the decision log can compare sessions with and without it. While the log is on, the prediction is recorded either way. collect-batch takes --hint off|on|ab.

Reports

npm run decision-report -- [--csv out.csv] turns the log into one row per search, labelled with what happened next (top result called, another result called, an operation not in the results called, or nothing called). Searches whose request matches a held-out test question in tests/user-queries.md are flagged so they can be kept out of training. When the hint runs in ab mode, the report also compares sessions that saw it with sessions that did not. npm run train-decision trains the model on these rows and compares it with the confidence thresholds on held-out questions.

Setup

First, create a service account in VSP 360 and note its client ID and secret. Give it the access your use case needs: admin covers alerts, logs and system operations; for devices, use a group whose access policy covers the device types.

Then install the server in one of these ways. Each GitHub release has the packages and a SHA256SUMS file.

Standalone. Unpack the archive anywhere and use bin/vsp360-mcp (bin\vsp360-mcp.cmd on Windows) as the server command. You can symlink it onto your PATH:

tar -xzf vsp360-mcp-0.1.16-linux-x64.tar.gz -C /opt && ln -s /opt/vsp360-mcp-0.1.16-linux-x64/bin/vsp360-mcp /usr/local/bin/vsp360-mcp

npm or CI/CD. Install straight from the release URL. The vsp360-mcp command then starts the server:

npm install -g https://github.com/visubramaniam/vsp360-mcp/releases/download/v0.1.16/vsp360-mcp-0.1.16.tgz

The examples below use vsp360-mcp as the command; substitute the path from whichever install you chose.

Claude Code

claude mcp add vsp360 -e VSP360_URL=https://vsp360.example.com -e VSP360_CLIENT_ID=my-service-account -e VSP360_CLIENT_SECRET=REPLACE_ME -e "VSP360_TOOLSETS=Device Registry,Platform Alerts" -- vsp360-mcp

Claude Desktop

The .mcpb package is the easiest way. To configure it by hand instead, add this to ~/Library/Application Support/Claude/claude_desktop_config.json. Claude Desktop does not read your shell’s PATH, so give the command’s full path, e.g. /usr/local/bin/vsp360-mcp:

{
  "mcpServers": {
    "vsp360": {
      "command": "/usr/local/bin/vsp360-mcp",
      "env": {
        "VSP360_URL": "https://vsp360.example.com",
        "VSP360_CLIENT_ID": "my-service-account",
        "VSP360_CLIENT_SECRET": "REPLACE_ME",
        "VSP360_TOOLSETS": "Device Registry,Platform Alerts"
      }
    }
  }
}

To try the tools interactively, run npm run inspect. It opens the MCP Inspector and needs the environment variables set in your shell.

Configuration

These settings belong to the optional search-improvement tools (Improving search); none is needed to use the server:

Tag names for VSP360_TOOLSETS

Users · Groups · Group Access · Service Accounts · Roles · Identity Providers · Active Directory · Authentication Settings · Authorization · Access Catalog · Access Policies · Privileged Access Management · Block Single Sign-On · Device Registration · Device Registry · Device Operation Jobs · File and Object Device Registration · Host and Hypervisor Discovery · Platform Alerts · VSP 360 Cluster Health · Logs · Diagnostics · Platform Profiles · Resource Management · Platform Upgrade · Application Lifecycle · TLS Certificates · Trusted CA Certificates · Notifications · Usage and Billing Reports · Product Information · Data Protection / Copies · Data Protection / Policies · Orchestration / Execute Workflows · Analytics / Query API

Building the packages

npm run package builds every release package into release/. Use --only npm,mcpb,standalone and --targets linux-x64,... to build fewer, e.g. npm run package -- --only standalone --targets darwin-arm64. The standalone packages bundle Node.js 24, downloaded from nodejs.org and checked against its published SHA-256 sums.

The Release workflow runs when a v* tag is pushed. It runs the tests, builds the packages and attaches them to the tag’s GitHub release; if that release doesn’t exist yet, it’s created from the version’s CHANGELOG.md section. If the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repository secrets are set, it also pushes the linux/amd64 and linux/arm64 Docker image. To rebuild an existing tag’s packages, run the workflow by hand with that tag.

Updating for a new VSP 360 release

Replace spec/Platform-vsp360-openapi.yaml (or point VSP360_SPEC at the new file) and restart the server. No code is generated from the spec, so nothing needs rebuilding. If the new release adds POST operations that only read data, add them to READ_ONLY_POSTS in src/spec.ts.

License

The code in this repository is released under the MIT License. The VSP 360 OpenAPI definition in spec/ describes Hitachi Vantara’s product API and is not covered by this license.