Parallel Works 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

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

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]