Parallel Works MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with the Parallel Works ACTIVATE REST API. This allows code assist agents to manage Parallel Works resources including clusters, storage, workflows, and more.

Features

The MCP server provides tools for managing:

Clusters: List and query compute clusters and nodes
Workflows: List, inspect, and execute workflows
Storage: Manage buckets, Lustre filesystems, and NFS storage
Sessions: View and manage user sessions
Allocations: Query budget allocations and usage
Machine Learning: List and manage ML workspaces (AWS SageMaker, Azure ML)
Kubernetes: Query Kubernetes clusters
User Resources: Get notifications, organizations, and groups

Installation

Prerequisites

Node.js 18+ or recent version
Parallel Works ACTIVATE account with API access

Setup

Clone or navigate to the project directory:

cd parallel-works-mcp

Install dependencies:

npm install

Configuration

The MCP server requires authentication to connect to the Parallel Works API. You can authenticate using either:

Option 1: API Key (Basic Auth)

export PARALLEL_WORKS_API_KEY="your-api-key-here"

Option 2: Bearer Token (JWT)

export PARALLEL_WORKS_TOKEN="your-jwt-token-here"

Optional: Custom API URL

export PARALLEL_WORKS_API_URL="https://activate.parallel.works"

Usage

Running the Server

Start the MCP server with stdio transport:

npm start

Or using Node directly:

node src/index.js

With custom API URL:

node src/index.js --api-url https://activate.parallel.works --api-key YOUR_KEY

With Bearer token:

node src/index.js --token YOUR_JWT_TOKEN

MCP Client Configuration

The recommended way to add the MCP server is by editing your ~/.claude.json configuration file directly:

# Open your Claude config file
nano ~/.claude.json

Add the MCP server configuration to each project where you want to use it:

{
  "projects": {
    "/your/project/path": {
      "mcpServers": {
        "parallelworks": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/parallel-works-mcp/src/index.js"],
          "env": {
            "PARALLEL_WORKS_API_KEY": "your-api-key-here"
          }
        }
      },
      "enabledMcpjsonServers": ["parallelworks"]
    }
  }
}

Configuration options: | Field | Value | |-------|-------| | type | "stdio" - standard input/output communication | | command | "node" - Node.js runtime | | args | Array with absolute path to src/index.js | | env.PARALLEL_WORKS_API_KEY | Your Parallel Works ACTIVATE API key | | enabledMcpjsonServers | ["parallelworks"] - enables the server |

To enable for all projects, add the same configuration under each project path in your ~/.claude.json file.

Available Tools

Authentication & User Info

`get_auth_session`

Get the current authentication session and user information.

{}

`get_organizations`

List organizations the user can access.

{}

`get_groups`

Get groups for the authenticated user.

{
  "provider": "aws-slurm",
  "network": "my-network"
}

Cluster Operations

`list_clusters`

List all clusters the user can access.

{}

`get_cluster_nodes`

Get nodes for a specific compute cluster.

{
  "organization": "parallelworks",
  "user": "username",
  "clusterName": "my-cluster",
  "type": "compute"
}

Workflow Operations

`list_workflows`

List all workflows for the authenticated user.

{
  "filter": "workflows"
}

`get_workflow`

Get details of a specific workflow.

{
  "workflow": "my-workflow"
}

`get_workflow_yaml`

Get the YAML configuration of a workflow.

{
  "workflow": "my-workflow"
}

`run_workflow`

Run a workflow with optional input parameters.

{
  "workflow": "my-workflow",
  "inputs": {
    "param1": "value1",
    "param2": "value2"
  }
}

Storage Operations

`list_buckets`

List storage buckets the user can access.

{
  "permission": "edit",
  "provisioned": true
}

`list_lustre`

List Lustre filesystems the user can access.

{
  "permission": "mount",
  "provisioned": true
}

`list_nfs`

List NFS filesystems the user can access.

{
  "permission": "edit",
  "provisioned": true
}

Session Operations

`list_sessions`

List sessions for the authenticated user.

{
  "type": "tunnel",
  "subdomain": "my-subdomain"
}

Allocation Operations

`list_allocations`

List budget allocations the user can access.

{
  "limit": 50,
  "skip": 0,
  "name": "production",
  "sort": "-total"
}

Kubernetes Operations

`list_kubernetes_clusters`

List Kubernetes clusters accessible to the user.

{}

ML Workspace Operations

`list_ml_workspaces`

List Machine Learning Workspaces.

{
  "csp": "aws",
  "region": "us-west-2",
  "provisioned": true
}

Notifications

`get_notifications`

Get notifications for the authenticated user.

{
  "limit": 20,
  "skip": 0,
  "read": false
}

Example Conversations

Listing Clusters

User: List all my clusters
Assistant: [calls list_clusters] Here are your clusters...

Running a Workflow

User: Run the "data-processing" workflow with input dataset="s3://my-bucket/data"
Assistant: [calls run_workflow with workflow="data-processing", inputs={"dataset": "s3://my-bucket/data"}] Workflow started successfully...

Checking Storage

User: What Lustre filesystems do I have access to?
Assistant: [calls list_lustre] You have access to the following Lustre filesystems...

Managing Sessions

User: Show me all my active tunnel sessions
Assistant: [calls list_sessions with type="tunnel"] Here are your active tunnel sessions...

Error Handling

The MCP server handles errors gracefully:

Authentication errors: Check your API key or token
Network errors: Verify your network connection and API URL
Invalid parameters: Check the tool input schema
Resource not found: Verify resource names and permissions

All errors are returned with descriptive messages in the response.

Development

Project Structure

parallel-works-mcp/
├── src/
│   └── index.js          # Main MCP server implementation
├── package.json           # Dependencies and scripts
├── pw-openapi.json       # OpenAPI specification (reference)
├── PROGRESS.md           # Development progress tracking
└── README.md             # This file

Adding New Tools

To add a new tool:

Add the tool definition to the tools array in src/index.js
Add a case in the CallToolRequestSchema handler
Test the tool with your MCP client

Example:

{
  name: 'my_new_tool',
  description: 'Does something useful',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'First parameter' },
    },
    required: ['param1'],
  },
}

API Reference

This MCP server is based on the Parallel Works ACTIVATE OpenAPI specification:

Base URL: https://activate.parallel.works
Documentation: Parallel Works Docs
OpenAPI Spec: Included as pw-openapi.json

License

MIT

Support

For issues or questions:

Parallel Works Support: support@parallelworks.com
GitHub Issues: [Create an issue in the repository]

Parallel Works MCP Server