Configuring AI Assistants

Complete guide for configuring AI assistants (Claude Code, GitHub Copilot) to work with Torc.

Overview

Torc provides an MCP (Model Context Protocol) server that enables AI assistants to interact with workflows. The torc-mcp-server binary acts as a bridge between AI assistants and the Torc HTTP API.

Available Tools

The AI assistant has access to these Torc operations:

Tool	Description
`get_workflow_status`	Get workflow info with job counts by status
`get_job_details`	Get detailed job info including resource requirements
`get_job_logs`	Read stdout/stderr from job log files
`list_failed_jobs`	List all failed jobs in a workflow
`list_jobs_by_status`	Filter jobs by status
`check_resource_utilization`	Analyze resource usage and detect OOM/timeout issues
`update_job_resources`	Modify job resource requirements
`restart_jobs`	Reset and restart failed jobs
`resubmit_workflow`	Regenerate Slurm schedulers and submit new allocations
`cancel_jobs`	Cancel specific jobs
`create_workflow_from_spec`	Create a workflow from JSON specification

Environment Variables

Variable	Description	Default
`TORC_API_URL`	Torc server URL	`http://localhost:8080/torc-service/v1`
`TORC_OUTPUT_DIR`	Directory containing job logs	`output`
`TORC_PASSWORD`	Password for authentication (optional)	—

Claude Code Configuration

Configuration Scopes

Claude Code supports MCP configuration at three scopes:

Scope	File	Use Case
Project	`.mcp.json` in project root	Team-shared configuration (commit to git)
Local	`.mcp.json` with `--scope local`	Personal project settings (gitignored)
User	`~/.claude.json`	Cross-project personal tools

CLI Commands

# Add the Torc MCP server
claude mcp add torc \
  --scope project \
  -e TORC_API_URL=http://localhost:8080/torc-service/v1 \
  -e TORC_OUTPUT_DIR=/path/to/your/output \
  -- /path/to/torc-mcp-server

# List configured MCP servers
claude mcp list

# Get details about the torc server
claude mcp get torc

# Remove the MCP server
claude mcp remove torc

Manual Configuration

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "torc": {
      "command": "/path/to/torc-mcp-server",
      "env": {
        "TORC_API_URL": "http://localhost:8080/torc-service/v1",
        "TORC_OUTPUT_DIR": "/path/to/your/output"
      }
    }
  }
}

Environment Variable Expansion

You can use environment variable expansion in .mcp.json:

{
  "mcpServers": {
    "torc": {
      "command": "/path/to/torc-mcp-server",
      "env": {
        "TORC_API_URL": "${TORC_API_URL:-http://localhost:8080/torc-service/v1}",
        "TORC_OUTPUT_DIR": "${TORC_OUTPUT_DIR:-./output}"
      }
    }
  }
}

VS Code + GitHub Copilot Configuration

Prerequisites

VS Code 1.99 or later
GitHub Copilot extension installed
GitHub Copilot subscription (Business, Enterprise, Pro, or Pro+)

Configuration

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "torc": {
      "command": "/path/to/torc-mcp-server",
      "env": {
        "TORC_API_URL": "http://localhost:8080/torc-service/v1",
        "TORC_OUTPUT_DIR": "./output"
      }
    }
  }
}

Verify Setup

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run "MCP: List Servers"
Verify "torc" appears in the list

Usage

In Copilot Chat, use Agent Mode (@workspace or the agent icon) to access MCP tools.

VS Code Remote SSH for HPC

For users running Torc on HPC clusters, VS Code's Remote SSH extension allows you to use Copilot Chat with the MCP server running directly on the cluster.

Architecture

┌─────────────────────┐         ┌─────────────────────────────────────┐
│  Local Machine      │   SSH   │  HPC Cluster                        │
│                     │◄───────►│                                     │
│  VS Code            │         │  torc-mcp-server ◄──► torc-server   │
│  (Copilot Chat)     │         │        ▲                            │
│                     │         │        │                            │
└─────────────────────┘         │  .vscode/mcp.json                   │
                                └─────────────────────────────────────┘

The MCP server runs on the HPC, communicates with the Torc server on the HPC, and VS Code proxies requests through SSH. No ports need to be exposed to your local machine.

Step 1: Build `torc-mcp-server` on the HPC

# On the HPC (via SSH or login node)
cd /path/to/torc
cargo build --release -p torc-mcp-server

Step 2: Configure MCP in your project

Create .vscode/mcp.json in your project directory on the HPC:

{
  "servers": {
    "torc": {
      "command": "/path/on/hpc/torc/target/release/torc-mcp-server",
      "env": {
        "TORC_API_URL": "http://localhost:8080/torc-service/v1",
        "TORC_OUTPUT_DIR": "./output"
      }
    }
  }
}

Important: MCP servers configured in workspace settings (.vscode/mcp.json) run on the remote host, not your local machine.

Step 3: Connect and use

Install the Remote - SSH extension
Connect to the HPC: Remote-SSH: Connect to Host...
Open your project folder on the HPC
Open Copilot Chat and use Agent Mode

HPC-Specific Tips

Module systems: If your HPC uses modules, you may need to set PATH in the env to include required dependencies
Shared filesystems: Place .vscode/mcp.json in a project directory on a shared filesystem accessible from compute nodes
Firewalls: The MCP server only needs to reach the Torc server on the HPC's internal network