Gcnv Mcp Server

Google Cloud NetApp Volumes MCP Server

A Model Context Protocol (MCP) server for managing Google Cloud NetApp Volumes (GCNV) resources through AI assistants such as Gemini CLI, Cursor, and other MCP-compatible clients.

Supported Resources

| Resource | Operations | | --------------------- | ----------------------------------------------------------------------------------- | | Storage Pools | create, get, list, update, validate directory service | | Volumes | create, get, list, update | | Snapshots | create, get, list, update, revert | | Backup Vaults | create, get, list, update | | Backups | create, get, list, update, restore, restore files | | Backup Policies | create, get, list, update | | Replications | create, get, list, update, stop, resume, reverse direction, sync, establish peering | | Active Directory | create, get, list, update | | KMS Configs | create, get, list, update, verify, encrypt volumes | | Quota Rules | create, get, list, update | | Host Groups | create, get, list, update | | Operations | get, list, cancel | | ONTAP Expert Mode | discover and execute supported ONTAP REST operations for ONTAP-mode pools |

Prerequisites

• Node.js 20.19.0 or higher
• A Google Cloud project with the NetApp Volumes API enabled
• Google Cloud authentication credentials (see [Authentication](#authentication))

Quick Start

Run the published package directly (no local build required):

npx gcnv-mcp-server@latest --transport stdio

MCP client config examples

Most MCP clients need the same stdio server command:

{
  "command": "npx",
  "args": ["-y", "gcnv-mcp-server@latest", "--transport", "stdio"]
}

For clients that use the common mcpServers JSON shape:

{
  "mcpServers": {
    "gcnv": {
      "command": "npx",
      "args": ["-y", "gcnv-mcp-server@latest", "--transport", "stdio"]
    }
  }
}

For VS Code-style MCP configuration:

{
  "servers": {
    "gcnv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gcnv-mcp-server@latest", "--transport", "stdio"]
    }
  }
}

Client config file locations and JSON wrappers vary by application. See the official MCP server setup docs and the VS Code MCP configuration reference for client-specific details.

Client CLI examples

Claude Code:

claude mcp add gcnv -- npx -y gcnv-mcp-server@latest --transport stdio
claude mcp list

Codex CLI:

codex mcp add gcnv -- npx -y gcnv-mcp-server@latest --transport stdio
codex mcp list

See the Claude Code MCP quickstart and OpenAI Codex MCP docs for more client-specific options.

Gemini CLI / Antigravity support

Gemini CLI extension users can install this repository as an extension:

# 1. Authenticate
gcloud auth login
gcloud auth application-default login

# 2. Install the extension
gemini extension install 

# 3. Verify
gemini mcp list

> Gemini automatically starts the MCP server when a linked extension needs it. No manual npm start is required for normal usage.

Antigravity / AGY users can install the repository as a plugin:

agy plugin install 
agy plugin list

If you previously installed the Gemini CLI extension, migrate existing Gemini extensions:

agy plugin import gemini

You can also configure the MCP server directly in the shared MCP config at ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "gcnv": {
      "command": "npx",
      "args": ["-y", "gcnv-mcp-server@latest", "--transport", "stdio"]
    }
  }
}

Restart Antigravity or run agy, then use /mcp to verify the server is loaded. See the Google Antigravity MCP codelab for more details on Antigravity MCP configuration.

Assistant Context Files

This repository includes assistant context files for clients that support repository guidance:

• AGENTS.md — shared GCNV safety and operating guidance.
• CLAUDE.md — Claude/Cursor compatibility shim that points to AGENTS.md.
• GEMINI.md — Gemini CLI extension context.

These files do not require a separate install step. Compatible clients load them automatically when using the repo or extension.

Authentication

Google NetApp Volumes API calls need a Google access token. How that token is supplied depends on the MCP transport and caller.

Application Default Credentials (ADC) — default for stdio CLI clients

Use ADC when running locally with Gemini CLI, Cursor, Claude Code, or other stdio MCP clients:

gcloud auth application-default login

Or point at a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

No extra environment variables are required. The server obtains a token from ADC for each tool call.

HTTP/SSE — per-request bearer header

For HTTP or SSE transport, send a bearer token on each MCP HTTP request to override ADC for that request only. This path is independent of stdio delegated auth.

By default the server reads Authorization: Bearer . Customize the header name with GCNV_AUTH_HEADER:

export GCNV_AUTH_HEADER="X-Google-Access-Token"

Then send requests with:

X-Google-Access-Token: Bearer 

Stdio delegated access token

Stdio MCP has no HTTP headers. A trusted parent process that spawns this server as a subprocess can inject a per-user Google access token via a runtime-only tool argument: _stdio_delegated_google_access_token.

This is disabled by default so public stdio clients cannot supply arbitrary bearer tokens via tool arguments.

Enable only when the MCP server is spawned by a fully controlled trusted subprocess:

export GCNV_STDIO_DELEGATED_ACCESS_TOKEN=true

When enabled:

• The runtime arg is never advertised in list_tools schemas.
• It is stripped before tool handlers run and is never logged.
• It overrides ADC for that tool call only.
• HTTP clients should continue to use the bearer header path above; Gemini CLI and other public stdio clients should use ADC.

| Transport | Token source | Environment | | ------------------------------ | -------------------------------------------------- | ---------------------------------------- | | stdio (CLI) | ADC | none | | stdio (delegated access token) | _stdio_delegated_google_access_token runtime arg | GCNV_STDIO_DELEGATED_ACCESS_TOKEN=true | | HTTP/SSE | Authorization (or GCNV_AUTH_HEADER) | none |

ONTAP KG Discover (Query-Only, Optional)

To externalize ONTAP discover ranking, set a knowledge endpoint and the server will call it per query.

| Variable | Purpose | | --------------------- | ------------------------------------------------------------ | | ONTAP_KG_URL | Full discover endpoint URL (MCP sends POST to this value) | | ONTAP_KG_AUTH_TOKEN | Optional bearer token used to authenticate to the KG service | | ONTAP_KG_TIMEOUT_MS | Optional timeout for KG discover requests (default 5000) |

Request/response contract is documented in [docs/ontap-kg-protocol.md](docs/ontap-kg-protocol.md) and schema in [schemas/ontap-kg.schema.json](schemas/ontap-kg.schema.json).

When the KG request fails or returns invalid payload, discover falls back to the bundled ontap-api-index.json.

Transport Modes

The server supports stdio (default) and HTTP/SSE transports.

Stdio (default)

Used automatically by Gemini CLI and other stdio-based MCP clients.

npm start                          # default stdio
npm run start:stdio                # explicit

HTTP/SSE

For web-based MCP clients or remote access.

npm run start:http                 # port 3000
npm start -- -t http -p 8080       # custom port

| Option | Description | Default | | ------------------- | ----------------- | ------- | | --transport, -t | stdio or http | stdio | | --port, -p | HTTP listen port | 3000 |

HTTP endpoint: http://localhost:/message

> Security note: The HTTP/SSE transport does not provide built-in TLS. If you expose it beyond a local trusted client, use customer-managed TLS and network access controls, such as a reverse proxy, VPN, service mesh, or SSH tunnel. Do not expose the MCP HTTP endpoint directly to the public internet.

Tool Reference

Storage Pool Tools

| Tool | Description | | ---------------------------------------------- | ----------------------------------------------------------- | | gcnv_storage_pool_create | Create a storage pool (FLEX / STANDARD / PREMIUM / EXTREME) | | gcnv_storage_pool_get | Get storage pool details | | gcnv_storage_pool_list | List storage pools (supports pagination and filtering) | | gcnv_storage_pool_update | Update pool capacity, description, labels, QoS, or type | | gcnv_storage_pool_validate_directory_service | Validate attached directory service |

Service level guidance:

• FLEX -- Smaller minimums, broader region availability, independent performance scaling. Minimum: 1024 GiB (FILE/UNIFIED) or 6144 GiB (UNIFIED large capacity).
• STANDARD / PREMIUM / EXTREME -- Classic tiers with fixed performance-to-capacity ratio. Minimum: 2048 GiB.
• serviceLevel is accepted case-insensitively (e.g. flex or FLEX).
• FLEX pools in a region-level location require both zone and replicaZone; zone-level locations satisfy this automatically.
• storagePoolType accepts FILE or UNIFIED; UNIFIED is only available for FLEX.
• scaleType: only set to SCALE_TYPE_SCALEOUT when creating a large capacity FLEX UNIFIED pool. Omit for all other pools (defaults to SCALE_TYPE_DEFAULT).
• mode: defaults to DEFAULT for a standard pool, or set to ONTAP to create an ONTAP-mode pool that exposes advanced ONTAP features (SnapMirror, QoS policies, direct ONTAP REST access) via the [ONTAP Expert Mode Tools](#ontap-expert-mode-tools). ONTAP mode requires serviceLevel: FLEX and storagePoolType: UNIFIED.

Volume Tools

| Tool | Description | | -------------------- | --------------------------------------------------------------------------- | | gcnv_volume_create | Create a volume (NFS, SMB, or iSCSI) | | gcnv_volume_get | Get volume details including mount points | | gcnv_volume_list | List volumes with pagination and filtering | | gcnv_volume_update | Update capacity, description, labels, export policy, tiering, backup config |

iSCSI notes: Protocols must be ["ISCSI"] only (no mixing). Requires hostGroup or hostGroups. Optional blockDevice object with identifier, osType (LINUX / WINDOWS / ESXI), and sizeGib.

Large capacity volumes: Some workloads require larger volumes and higher throughput, which can be achieved by using the large capacity volume option for these service levels. Large capacity volumes provide six storage endpoints (IP addresses) to load-balance client traffic to the volume and deliver higher performance.

• FLEX Unified: Large capacity volumes can be sized between 4.8 TiB and 2.48 PiB, or up to 20 PiB with auto-tiering, in increments of 1 GiB, and deliver throughput performance of up to 22 GiBps. The FLEX storage pool must be created with scaleType: SCALE_TYPE_SCALEOUT; non-scale-out FLEX pools cannot host large capacity volumes. When largeCapacityConstituentCount is explicitly set, the minimum drops to 2.4 TiB (2,400 GiB) — FLEX Unified only. When largeCapacityConstituentCount is omitted, the 4.8 TiB (4,916 GiB) floor applies.
• Premium and Extreme: Large capacity volumes can be sized between 15 TiB and 3 PiB in increments of 1 GiB, and deliver throughput performance of up to 30 GiBps.

A large capacity volume is internally composed of several constituent volumes (FlexVols) distributed across the pool's storage aggregates. On gcnv_volume_create you can optionally pass largeCapacityConstituentCount to control how many constituents the volume is built from:

• Minimum: 2.
• Default (when omitted): chosen by the backend based on the active deployment layout.
• The constituent count must be chosen at create time and cannot be changed later.

SMB attributes: When protocols includes SMB, gcnv_volume_create accepts optional SMB feature flags that map to the smbSettings field on the volume:

• smbEncryptData: true → ENCRYPT_DATA (require SMB encryption in flight)
• smbHideShare: true → NON_BROWSABLE (hide the share from browse lists)
• smbAccessBasedEnumeration: true → ACCESS_BASED_ENUMERATION (ABE) — controls the visibility of files and folders based on the permissions assigned to the user
• smbContinuouslyAvailable: true → CONTINUOUSLY_AVAILABLE (CA share for SQL Server / FSLogix; choice is permanent on the volume)
• smbSettings: ["OPLOCKS", ...] — additional API enum values; merged with the booleans above. Do not pass SMB_SETTINGS_UNSPECIFIED; BROWSABLE and NON_BROWSABLE (or BROWSABLE together with smbHideShare) are rejected. NON_BROWSABLE and CONTINUOUSLY_AVAILABLE together (or smbHideShare with smbContinuouslyAvailable) are also rejected — CA shares must be browsable.

These flags require protocols to include SMB. CONTINUOUSLY_AVAILABLE is not supported on FLEX storage pools — the request is rejected before reaching the API. Use STANDARD, PREMIUM, or EXTREME for CA shares.

FlexCache: On default-mode pools, use gcnv_volume_create with cacheParameters to create a cache volume (origin cluster, SVM, volume, and intercluster LIF IPs). Use gcnv_volume_update with cacheParameters.cacheConfig to change cache settings. On ONTAP-mode pools, use [ONTAP Expert Mode Tools](#ontap-expert-mode-tools) instead.

Snapshot Tools

| Tool | Description | | ---------------------- | ------------------------------------- | | gcnv_snapshot_create | Create a snapshot of a volume | | gcnv_snapshot_get | Get snapshot details | | gcnv_snapshot_list | List sna

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NetApp
• Source: NetApp/gcnv-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.