PW MCP Toolset Documentation - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

PW MCP Toolset Documentation — 26 Tools for Cloud Infrastructure AI

Version: 7.26.0 (SDD Phase 37 Complete) Server: parallel-works-mcp (Node.js MCP Server) API Target: https://noaa.parallel.works (Parallel Works v7.15.1) Last Updated: March 6, 2026

Overview

The Parallel Works MCP (Model Context Protocol) Server provides 26 tools that give AI assistants direct access to the NOAA RDHPCS Hybrid Cloud platform. These tools enable AI-driven infrastructure management, cost analysis, and operational monitoring across AWS, Google Cloud, and Azure environments.

The server connects to the Parallel Works REST API and translates cloud infrastructure operations into structured MCP tool calls that AI clients (VS Code Copilot, Claude, CLI agents) can invoke programmatically.

Tool Categories

1. Authentication & Platform (3 tools)

Tool Description Returns
get_auth_session Current user identity, roles, features, sidebar modules User profile, org membership, feature flags
get_platform_settings Platform version, maintenance status, auth config Version, features, theme, module list
get_organizations Organization details and member count Org name, description, member count

2. Compute Management (4 tools)

Tool Description Returns
list_clusters All clusters across all CSPs with status Name, type, CSP, user, status, tags
get_cluster_status Detailed status for a specific cluster State, nodes, agent version, controller info
get_cluster_nodes Login nodes for HPC proxy clusters Hostname, IP, last report time, roles
list_sessions Active interactive sessions (VNC, Jupyter) Session name, target, status, health, ports

3. Cost & Group Management (3 tools)

Tool Description Returns
get_groups Cloud resource groups with optional budgets Group name, CSP, members, budget/used/remaining
get_cost_summary Aggregated budget analysis across all groups Total budget, spent, remaining, per-CSP breakdown
list_allocations Resource allocation policies Allocation details (currently none active)

4. Storage (6 tools) — Enhanced in Phase 37

Tool Description Returns
list_storage ⭐ Unified view of all storage types Combined list of buckets, NFS, Lustre, disks
list_buckets Object storage (S3, GCS, Azure Blob) Name, CSP, region, status, owner
list_nfs Network file systems (EFS, Filestore) Name, CSP, size, status, shared groups
list_lustre High-performance parallel filesystems Name, CSP, region, ephemeral flag, tags
list_snapshots ⭐ VM and disk snapshots Name, CSP, region, size, creation date
get_resource_detail Full details for any resource by name Complete resource configuration

5. Networking (3 tools) — New in Phase 37

Tool Description Returns
list_networks ⭐ VPC networks across all CSPs Name, CSP, regions, provisioning mode, DNS
list_ips ⭐ Static/elastic IP addresses Name, IP, CSP, region, description, tags
list_kubernetes_clusters Managed Kubernetes (EKS, GKE, AKS) K8s cluster configuration (currently none)

6. Workflows & ML (4 tools)

Tool Description Returns
list_workflows Installed workflow definitions Name, type, source repo, branch
get_workflow Details for a specific workflow Full workflow configuration
get_workflow_yaml ⭐ Raw YAML definition of a workflow Complete YAML content
list_ml_workspaces ⭐ ML workspace instances Name, CSP, region, network, status

7. System (3 tools) — New/Enhanced in Phase 37

Tool Description Returns
list_resources ⭐ Unified view of ALL resource types Combined cluster, storage, network resources
get_notifications ⭐ Platform notifications and alerts Notification list (currently empty)
get_groups (enhanced) Now includes budget summaries per group Budget/used/remaining per group

⭐ = Added or significantly enhanced in Phase 37

Phase 37 Enhancement Details

SDD Phase 37: PW MCP Tool Expansion

Spec: sdd_framework/workflows/phase37_pw_mcp_tool_expansion.md Execution: 2 commits (50b89dd + 2f958fd), 548 insertions across src/index.js Result: Tools expanded from 19 → 26

New Tools Added (4)

  1. list_snapshots — Queries /api/v2/snapshots for VM/disk snapshots with CSP, region, size, and creation metadata
  2. list_storage — Composite tool that queries buckets, NFS, Lustre, and disks in parallel, returning a unified storage inventory
  3. list_networks — Queries /api/v2/networks for VPC configuration across AWS, Google, and Azure
  4. list_ips — Queries /api/v2/ips for static/elastic IP address inventory

Enhanced Tools (3)

  1. get_groups — Added include_budget parameter; now fetches budget summaries per group via /api/v2/groups/{name}/budget
  2. get_cost_summary — Now provides per-CSP breakdown derived from group naming conventions
  3. list_resources — Enhanced to return unified resource view across all types

Composite Tools (3)

  1. list_storage — Aggregates 4 API calls (buckets + NFS + Lustre + disks) into single response
  2. get_cost_summary — Aggregates all group budgets into organizational summary
  3. list_resources — Aggregates clusters, storage, and network resources

API Endpoint Coverage Map

The 26 tools cover the following PW REST API endpoints:

Endpoint Tool(s) Method
/api/v2/auth/session get_auth_session GET
/api/settings get_platform_settings GET
/api/v2/orgs get_organizations GET
/api/v2/groups get_groups GET
/api/v2/groups/{name}/budget get_groups, get_cost_summary GET
/api/v2/clusters list_clusters GET
/api/v2/clusters/{name} get_cluster_status GET
/api/v2/clusters/{name}/nodes get_cluster_nodes GET
/api/v2/sessions list_sessions GET
/api/v2/resources list_resources, get_resource_detail GET
/api/v2/buckets list_buckets, list_storage GET
/api/v2/nfs list_nfs, list_storage GET
/api/v2/lustre list_lustre, list_storage GET
/api/v2/disks list_storage GET
/api/v2/snapshots list_snapshots GET
/api/v2/networks list_networks GET
/api/v2/ips list_ips GET
/api/v2/kubernetes list_kubernetes_clusters GET
/api/v2/workflows list_workflows GET
/api/v2/workflows/{name} get_workflow GET
/api/v2/workflows/{name}/yaml get_workflow_yaml GET
/api/v2/ml-workspaces list_ml_workspaces GET
/api/v2/allocations list_allocations GET
/api/v2/notifications get_notifications GET

Total unique API endpoints: 24

Configuration

VS Code MCP Configuration (.vscode/mcp.json)

{
  "servers": {
    "parallel-works-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/parallel-works-mcp/src/index.js"],
      "env": {
        "PW_API_KEY": "<your-jwt-token>",
        "PW_PLATFORM_URL": "https://noaa.parallel.works"
      }
    }
  }
}

Environment Variables

Variable Required Description
PW_API_KEY ✅ JWT authentication token from PW platform
PW_PLATFORM_URL ✅ Platform base URL (e.g., https://noaa.parallel.works)

Token Refresh

JWT tokens expire periodically. When tools return 401 Unauthorized:

  1. Log into the PW platform web UI
  2. Open browser DevTools → Application → Cookies
  3. Copy the session cookie value
  4. Update PW_API_KEY in .vscode/mcp.json
  5. Restart the MCP server

Architecture

VS Code / Claude / CLI Agent
        │
        ▼ (MCP Protocol - stdio)
┌──────────────────────────┐
│  parallel-works-mcp      │
│  src/index.js (1,147 LOC)│
│  26 tools / 26 handlers  │
│  Node.js + @modelcontextprotocol/sdk │
└──────────────────────────┘
        │
        ▼ (HTTPS + JWT)
┌──────────────────────────┐
│  Parallel Works REST API │
│  noaa.parallel.works     │
│  v7.15.1                 │
│  24 endpoints            │
└──────────────────────────┘
        │
        ▼
┌──────────────────────────┐
│  Cloud Infrastructure    │
│  AWS / Google / Azure    │
│  35 clusters, 33 storage │
│  4 networks, 1 IP        │
└──────────────────────────┘

Related

Documentation generated March 6, 2026 from live PW MCP Server (26 tools) and SDD Phase 37 artifacts.