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

1. Clone or navigate to the project directory:

cd parallel-works-mcp

1. 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:

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:

1. Add the tool definition to the tools array in src/index.js
2. Add a case in the CallToolRequestSchema handler
3. 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: [email protected]
• GitHub Issues: [Create an issue in the repository]