Hitachi VSP 360 (Community)

vsp360-mcp: Community MCP server for Hitachi VSP 360

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.

Not an official Hitachi Vantara product: vsp360-mcp is an independent, community project, and isn't supported by or affiliated with Hitachi Vantara. Hitachi and VSP 360 are trademarks of their owners.

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. With HIGH confidence, the top result's parameters are listed too (types, enum values, required body fields), so Claude can usually call it without spending a turn on vsp360_describe_operation. This is skipped when the top result is blocked by the current settings, and for analyticsRunQuery, which needs describe's MQL reference. 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 (only with action=query)
• inventory filter query
• authorization check
• user capabilities
• CSV validation
• upgrade version validation

All other operations are refused, and direct tools are not created for them. These include device registration and deletion, the directory connection test (it makes VSP 360 connect to whatever LDAP host it's given), 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.

Operations that return secrets. Three operations return a live client secret, which would then become part of the conversation: the read vsp360GetServiceAccountSecret, and the writes vsp360RevealBlockSSOSetup and vsp360RotateBlockSSOSecret, which return a block storage SSO client secret. Every other operation masks secrets. These three are refused, whether or not writes are allowed, unless VSP360_ALLOW_SECRET_READS=true.

Connections. VSP360_URL must be https:// unless VSP360_ALLOW_HTTP=true. The token request never follows a redirect, and API requests follow redirects only within VSP360_URL, so the client secret and access token aren't sent anywhere else.

Over HTTP. With VSP360_TRANSPORT=http, the server answers MCP requests at http://127.0.0.1:8360/mcp instead of over stdio, for clients that connect to a URL or several clients sharing one server. Every request needs the bearer token in VSP360_HTTP_TOKEN; it serves plain HTTP on loopback only and needs a TLS certificate (VSP360_HTTP_TLS_CERT, VSP360_HTTP_TLS_KEY) to listen anywhere else, and it refuses requests whose Host doesn't name it or that come from a web page. Because the caller may be on another machine, uploads, save_to and binary downloads are turned off. See Run over HTTP and SECURITY.md.

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, checked with symlinks resolved, never into a hidden folder such as ~/.ssh, and never over an existing 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. In read-only mode, the one upload allowed (CSV validation) is refused unless VSP360_UPLOAD_DIR is set, because it would otherwise let a steered model send any local file to VSP 360.

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 fetch every page. When the first page's Link header gives both next and last, the remaining pages are fetched four at a time; otherwise the next links are followed one by one. max_pages caps the number of pages; it defaults to 20, and at most 200 are fetched. 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.
• Compact responses: JSON responses and vsp360_describe_operation output are returned without indentation, which is about 40% fewer characters for the model to read. Files written with save_to stay indented.
• Large responses: Responses longer than VSP360_MAX_RESPONSE_CHARS are truncated, with a note telling Claude how to narrow the request. A response larger than VSP360_MAX_RESPONSE_BYTES (64 MiB) isn't read into memory: the call fails and suggests save_to, which streams the response to a file. With all_pages, the limit covers all pages together, and the pages before it are kept.

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. The model abstains when it is unsure. It stores a probability cut-off (minP), chosen during training so that a shown suggestion is right at least two times in three, and suggestions below it are logged but not shown. Training labels requests the API has no operation for (no_api) separately from ones whose operation search ranked too low (search_miss). Both label schemes are trained, and the one with the better cross-validated accuracy (scored on the four classes both can produce) is kept, so the split is used only once there is enough data for it to help; SPLIT=1 or SPLIT=0 forces it. npm run train-decision reads both reports/decisions-batch.jsonl and reports/decisions.jsonl, and cross-validates by question so that several searches for the same question never land on both sides of a fold. npm test fails when the bundled model no longer matches the search index (any change to the spec, examples.json, search or the features) or stops beating the fixed confidence thresholds; retrain it when that happens. LABELLED_FILES=a.md,b.md adds labelled questions from other files in the tests/user-queries.md format; the bundled model is trained with LABELLED_FILES=tests/generated-questions.md, 811 questions generated from the VSP 360 documentation. tests/generate-questions.md has a prompt for generating them from the VSP 360 documentation, and explains how to check them and collect live decisions from them. 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 -- <log.jsonl> [--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

INSTALL.md has the full installation and deployment guide, including Windows, CI/CD pipelines, checksums, upgrading and troubleshooting. In short:

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.31-linux-x64.tar.gz -C /opt && ln -s /opt/vsp360-mcp-0.1.31-linux-x64/bin/vsp360-mcp /usr/local/bin/vsp360-mcp

npm or CI/CD. Install from the npm registry (version 0.1.17 and later). The vsp360-mcp command then starts the server:

npm install -g vsp360-mcp

Each GitHub release also has the same package as vsp360-mcp-<version>.tgz, for machines that can't reach the registry.

Claude Code plugin. The plugin/ folder packages the server with capacity, charting and health-check skills: /plugin install vsp360-community --marketplace visubramaniam/vsp360-mcp. See README.plugin.md for installing, configuring and using it.

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 run the server over HTTP instead of stdio (Run over HTTP):

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,skill 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 Claude Desktop extension is packed with npx @anthropic-ai/mcpb@2.1.2, which is downloaded when needed rather than kept as a dev dependency.

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. It then publishes the same .tgz to the npm registry with trusted publishing, so no npm token is stored and each version gets a provenance attestation; this is skipped if that version is already on npm. The trusted publisher is set up on npmjs.com under the package's Settings → Trusted Publisher (repository visubramaniam/vsp360-mcp, workflow release.yml). It pushes the linux/amd64 and linux/arm64 Docker image to ghcr.io/visubramaniam/vsp360-mcp using the workflow's own token, and also to Docker Hub if the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repository secrets are set. To rebuild an existing tag's packages, run the workflow by hand with that tag.

The Claude plugin in plugin/ installs the server from its own lockfile, so it can only use a version that's already on npm. After a release is published, update it in a follow-up pull request: set the version in plugin/package.json (its version and the vsp360-mcp dependency) and in plugin/.claude-plugin/plugin.json, then run npm install --package-lock-only --ignore-scripts in plugin/ to regenerate package-lock.json. tests/unit/plugin.test.mjs checks that the three agree, that the lockfile meets the directory's rules, and that the plugin isn't ahead of package.json.

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. npm run build keeps a pre-parsed copy of the bundled spec in dist/openapi-cache.json, so the server starts without parsing YAML. The copy is only used while the YAML file is unchanged, so a replaced file is parsed afresh, which adds about a quarter of a second to startup. Run npm run build again to refresh the copy. If the new release adds POST operations that only read data, add them to READ_ONLY_POSTS in src/spec.ts.

Contributing

Bug reports, search problems, documentation fixes and code are all welcome. CONTRIBUTING.md explains how to set up, test and submit a change, and the rules for keeping live VSP 360 data out of this public repository. Everyone taking part is expected to follow the Code of Conduct. Report security problems privately, as SECURITY.md describes.

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.