Skip to main content
Glama
Sign In
RISBridge MCP

RISBridge MCP

by CodeMonk6
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

RISBridge MCP

Run jobs on the WashU RIS Compute2 cluster by describing what you want. An intent-to-compute server that turns plain English into safe, validated Slurm work — no SSH, sbatch, partitions, GRES, modules, or storage layout to learn.

License Platform Scheduler Runtime Protocol Type

RISBridge is a Model Context Protocol server. You talk to it in plain language through an MCP client (Claude Desktop or Claude Code); it plans the job, shows you exactly what it will submit, and runs it on the cluster only after you confirm. It is deliberately not a terminal — there is no arbitrary-shell tool. Every action is a specific, schema-validated operation, which is what makes it safe to let an agent drive real HPC work.

Why it exists

Getting research code onto an HPC cluster usually means learning SSH, Duo, sbatch, partitions, GRES, modules, and a storage layout — before running a single line. RISBridge removes that wall:

  • Researchers new to HPC get a guided path — a setup wizard, plain-English planning, dry-run previews, and clear status/log/diagnose tools. No Slurm knowledge required.

  • Experienced HPC users get speed and consistency — job arrays, afterok pipelines, single-node multi-GPU torchrun, vLLM serving, efficiency right-sizing, run comparison, and reproducible history.

Same server, both audiences. The tools scale from "hold my hand" to "give me the template and get out of the way."

Related MCP server: qzcli

How it works

flowchart LR
    A([Plain-English intent]) --> B[Plan & validate<br/>partition · resources · paths]
    B --> C{Dry-run preview<br/>“I will submit: …”}
    C -- confirm --> D[Build sbatch from<br/>fixed, validated templates]
    D --> E[[SSH · Duo / multiplexing]]
    E --> F[(Slurm on Compute2)]
    F --> G[Monitor · logs · explain<br/>efficiency · history]
    G --> A

Login nodes are used only for submitting — every workload runs through Slurm on compute nodes. Submissions are dry-run by default and require an explicit confirm before anything reaches the scheduler.

Highlights

  • Intent → compute. "Run src/train.py on a GPU for 4 hours" becomes a validated sbatch submission. "Why is my job pending?" returns a plain-English answer with a fix.

  • Safe by construction. No arbitrary-shell tool; strict input validation; remote commands run via argument arrays (never shell strings); file uploads are base64-encoded; paths are workspace-confined; job control verifies ownership; a redacted audit log records every action.

  • Auth that respects policy. SSH-key setup, Duo-aware connection multiplexing (approve once, reuse for hours), and an optional per-user worker that orchestrates Slurm from inside the cluster. Duo is never automated; private keys are never shown or logged.

  • Broad workload coverage. Python (CPU/GPU), R, notebooks, GPU smoke tests, job arrays, multi-GPU training, vLLM serving, JupyterLab, conda environments, dependency pipelines, and long checkpoint/requeue runs.

  • 53 high-level tools across auth, discovery, projects/files, planning, submission, job management, logs, environments, expert controls, and the per-user worker.

Example

You type intent; RISBridge does the rest:

"What's my RISBridge setup status?" "Set up my SSH key." → installs the key, one Duo approval "Discover my profile." → finds your Slurm account and storage workspace "Run src/train.py on one H100 for 4 hours." → preview → confirm → job ID "Why is job 1234567 pending?" · "Tail its logs." · "Right-size my last 5 runs."

The toolset

Setup & authentication — ris_setup_wizard, ris_auth_status, ris_setup_ssh_key, ris_show_public_key, ris_generate_ssh_config, ris_write_ssh_config, ris_test_key_only_auth, ris_open_ssh_master, ris_check_ssh_master, ris_repair_stale_socket

Discovery & configuration — ris_discover_profile, ris_set_profile, ris_show_config, ris_validate_config, ris_list_partitions, ris_gpu_status

Projects, files & environments — ris_create_project, ris_upload_file, ris_list_project_files, ris_ensure_env, ris_list_modules, ris_list_conda_envs, ris_inspect_conda_env

Planning — ris_plan_run, ris_researcher_wizard, ris_estimate_resources

Submitting jobs — ris_run, ris_submit_python_job, ris_submit_r_job, ris_submit_notebook_job, ris_submit_gpu_smoke_test, ris_submit_array_job, ris_submit_multigpu_torch_job, ris_submit_jupyter_job, ris_submit_vllm_job, ris_submit_conda_env_job, ris_create_pipeline, ris_generate_sbatch_template

Monitoring & lifecycle — ris_list_my_jobs, ris_job_history, ris_explain_job, ris_get_job_logs, ris_tail_job_logs, ris_cancel_job, ris_hold_job, ris_release_job

Analysis & reproducibility — ris_analyze_efficiency, ris_compare_runs, ris_get_result_manifest

Per-user worker — ris_bootstrap_worker, ris_worker_enqueue, ris_worker_status, ris_worker_cancel

Safety & trust model

Guarantee

How

No arbitrary shell

Every remote command is a fixed template built from validated tokens; no raw command tool exists.

Injection-resistant

Zod validation on every input; spawn with argument arrays; base64-encoded uploads.

Confined

Workspace-only paths (no traversal, no data on /home).

Confirmed

Submissions are dry-run by default and need an explicit confirm.

Accountable

Ownership-checked job control; redacted append-only audit log.

Private

Duo never automated; passwords never captured; private keys never shown or logged.

Requirements

  • A WashU RIS account with a Compute2 allocation.

  • The WashU network or VPN (login nodes are reachable only on-network) and Duo MFA.

  • An MCP client (Claude Desktop or Claude Code). For the source route: Node.js 18.18+ and OpenSSH.

Getting started

Use is governed by the license — the steps below are for authorized users.

One-click extension. Install the risbridge-mcp.mcpb Desktop Extension in Claude Desktop (Settings → Extensions → Install Extension…), enter your WashU username, and you're done — it bundles its own runtime.

From source.

npm install
npm test          # unit tests (no network)
npm run build     # → dist/
node dist/cli.js tools     # list the registered tools

Then register the server with your client (for example: claude mcp add risbridge -- node /abs/path/dist/server.js), connect to the WashU VPN, and ask RISBridge to set up your SSH key.

Cluster reference

Partitions (there is no plain general partition):

Partition

Use

GPU

general-gpu

Full-throughput GPU work

Full H100 80 GB

general-preempt-gpu

Free, restartable GPU work

Untyped (preemptible)

general-cpu

Standard CPU work

—

general-short

Quick tests / dev

MIG slice (~10 GB)

general-interactive

Interactive sessions

MIG slice

general-bigmem

Large-memory CPU

—

Storage — /home is small (code only); data, environments, outputs, and checkpoints live under your /storage2/fs1/<lab>/Active/... workspace.

GPU requests — typed --gres=gpu:H100:N by default; untyped --gres=gpu:N is opt-in and matches more nodes on general-gpu (and is required on preemptible GPU queues).

Project structure

src/
  tools/        53 MCP tools
  core/         sbatch builder (policy chokepoint), ssh/slurm clients, validation, planner
  templates/    12 job templates
  auth/         SSH key + Duo / multiplexing
  worker/       per-user worker daemon
  config.ts     environment-driven configuration
tests/          unit test suite
scripts/        installers + .mcpb packaging

License

Proprietary — All Rights Reserved. This software and its source code are proprietary and confidential. No license or permission is granted to use, copy, modify, or distribute it, in whole or in part, without the prior written permission of the copyright holder. Viewing this repository does not grant any such rights. See LICENSE.

To request permission, contact sourabh@wustl.edu.

Available Tools

53 tools
ris_analyze_efficiencyAnalyze efficiencyA
Read-only

Use seff/sacct to recommend right-sizing for a job or your recent runs.

Inputs: jobId, lastN, profile.

ris_auth_statusRIS auth statusB
Read-only

Snapshot of local SSH-auth state (key, managed config, mux master) and whether the agent can run RIS commands hands-free. deep=true also runs the decisive key-only login test.

Inputs: deep, host, user, alias, +1 more.

ris_bootstrap_workerBootstrap RIS workerB

Set up the per-user worker: create the control-plane dirs under /.risbridge and submit a low-resource general-cpu daemon that submits/polls jobs for you (minimizes repeat Duo logins). dryRun preview by default.

Inputs: dryRun, account, profile, walltime, +1 more.

ris_cancel_jobCancel jobA
Destructive

Cancel one of YOUR jobs (ownership verified first). Requires confirm=true. jobId optional only when a project scope is given (cancels the latest in that project).

Inputs: jobId, confirm, profile, project.

ris_check_ssh_masterCheck multiplexing masterA
Read-only

Check the ControlMaster via ssh -O check AND a functional ssh true probe.

Inputs: alias, profile.

ris_compare_runsCompare runsB
Read-only

Side-by-side comparison of 2+ jobs (resources, exit state, elapsed, efficiency).

Inputs: jobIds (required), profile.

ris_create_pipelineCreate pipelineA

Submit a chain of Python jobs with --dependency=afterok between stages. dryRun preview by default; confirm to submit the chain.

Inputs: stages (required), project (required), dryRun, account, +2 more.

ris_create_projectCreate project workspaceB

Create the standard project directory tree (src/ data/{raw,interim,processed}/ models/ outputs/ logs/ sbatch/ envs/ configs/ checkpoints/ manifests/ tmp/) under your /storage workspace.

Inputs: project (required), dryRun, profile.

ris_discover_profileDiscover RIS profileA
Read-only

Read-only probe of your RIS identity: username, Slurm accounts/QOS, and WRITABLE storage workspaces (derived from your groups and live-tested). Presents candidates and asks you to confirm — it never picks for you.

Inputs: profile.

ris_ensure_envEnsure environmentA

Make sure a conda environment exists for a project, building it automatically (PyTorch on the CUDA-12.4 wheels by default) if missing — zero manual steps. dryRun preview by default; confirm to build.

Inputs: project (required), dryRun, python, account, +5 more.

ris_estimate_resourcesEstimate resourcesC
Read-only

Suggest cpus/mem/gpus/walltime/partition from a description (heuristic, offline).

Inputs: epochs, jobType, profile, gpuCount, +3 more.

ris_explain_jobExplain jobA
Read-only

Plain-English why-pending / why-failed for a job: state + reason + efficiency (seff) + a log tail, with a practical fix. jobId optional — defaults to your most recent job (or the latest in a given project).

Inputs: jobId, profile, project, tailLines.

ris_generate_sbatch_templateGenerate sbatch templateA
Read-only

Render a ready-to-edit sbatch script for any job type. Generate only — never submits.

Inputs: jobType (required), cpus, memGb, account, +5 more.

ris_generate_ssh_configPropose SSH config blockA
Read-only

Render the managed ~/.ssh/config block (with multiplexing) and a diff. Does NOT write anything.

Inputs: host, user, alias, profile, +1 more.

ris_get_job_logsGet job logsB
Read-only

Fetch a job's stdout/stderr (byte-capped, restricted to its log files). jobId optional — defaults to your most recent job.

Inputs: jobId, stream, profile, project, +1 more.

ris_get_result_manifestGet result manifestC
Read-only

Read a run's manifest JSON from project/manifests, or list available manifests. Cross-references local run history.

Inputs: project (required), runId, profile.

ris_gpu_statusH100 availabilityB
Read-only

Per-node H100 free/used on the GPU partition (full H100s only; MIG slices excluded).

Inputs: profile, partition.

ris_hold_jobHold jobA
Destructive

Hold one of YOUR pending jobs (ownership verified). Requires confirm=true. jobId optional only with a project scope.

Inputs: jobId, confirm, profile, project.

ris_inspect_conda_envInspect conda envB
Read-only

List packages in a named or path-based conda env.

Inputs: envName, envPath, profile, project.

ris_job_historyJob historyA
Read-only

Recent finished jobs via sacct, merged with local run history.

Inputs: limit, profile, project, sinceDays.

ris_list_conda_envsList conda envsA
Read-only

List conda environments visible on RIS (base + project-local).

Inputs: profile, project.

ris_list_modulesList RIS modulesC
Read-only

List available Lmod modules on RIS (optionally filtered).

Inputs: filter, profile.

ris_list_my_jobsList my jobsA
Read-only

Show your current Slurm queue (running/pending), optionally filtered by state or project.

Inputs: state, profile, project.

ris_list_partitionsList partitionsB
Read-only

Show RIS Compute2 partitions with availability and plain-English notes (MIG vs full H100, preempt, no plain general).

Inputs: profile, partition.

ris_list_project_filesList project filesB
Read-only

List files in a project (or a subdir) with depth and entry caps.

Inputs: project (required), subdir, profile, maxDepth, +1 more.

ris_open_ssh_masterOpen multiplexing masterB

Best-effort open of the ControlMaster session; on a Duo host it returns the exact interactive command to run in a real terminal (approve Duo once, then the agent reuses the socket).

Inputs: alias, profile.

ris_plan_runPlan a runB
Read-only

Turn an intent into a safe, validated resource plan (CPU vs GPU, partition, cpus/mem/gpus/walltime, smoke-test recommendation) in plain English. Does NOT submit.

Inputs: gpuNeed, maxGpus, profile, project, +5 more.

ris_release_jobRelease jobA
Destructive

Release one of YOUR held jobs (ownership verified). Requires confirm=true. jobId optional only with a project scope.

Inputs: jobId, confirm, profile, project.

ris_repair_stale_socketRepair stale mux socketA
Destructive

Remove ONLY the exact, verified stale ControlPath socket (five safety guards). Use when the master is gone but a dead socket blocks reconnection.

Inputs: alias, profile.

ris_researcher_wizardResearcher wizardA
Read-only

For non-HPC users: from a plain-English goal and a few optional hints, infer a safe plan and the exact next ris_submit_* call. Does NOT submit.

Inputs: goal (required), profile, project, needsGpu, +3 more.

ris_runRun a script (auto-setup)A

One call: ensures your project + environment exist (auto-builds a PyTorch/TF env if missing) and submits your script — GPU or CPU. No manual conda steps. dryRun preview by default; re-call with dryRun=false, confirm=true to run.

Inputs: script (required), project (required), dryRun, account, +7 more.

ris_set_profileSet RIS profileA
Destructive

Save your confirmed username + Slurm account + storage workspace to ~/.risbridge-mcp/config.json. Validates the account is yours and the workspace is writable (unless force). Requires confirm=true.

Inputs: username (required), workspace (required), slurmAccount (required), force, +4 more.

ris_setup_ssh_keySet up dedicated SSH keyA
Destructive

Create the dedicated ed25519 key (chmod 600) if absent and show the public key + install command. The private key is never returned. Pass overwrite=true to replace an existing key.

Inputs: comment, profile, overwrite.

ris_setup_wizardGuided RIS setupB
Read-only

Personalized, plain-English setup checklist. It inspects your current state (WashU username, SSH key, SSH config, Duo/hands-free auth, account & workspace) and tells you the single next step. Read-only — it never changes anything; it points you at the exact tool or command to run next.

Inputs: host, user, alias, profile.

ris_show_configShow RIS configB
Read-only

Show the active resolved profile (username, account, workspace, partitions) and the profiles saved in config.json.

Inputs: profile.

ris_show_public_keyShow public keyB
Read-only

Print the dedicated public key and its fingerprint. The private key is never read.

Inputs: profile.

ris_submit_array_jobSubmit array jobC

Run a project script across a bounded Slurm array (the script reads $SLURM_ARRAY_TASK_ID). Total tasks capped at 10000.

Inputs: script (required), project (required), arrayEnd (required), arrayStart (required), +17 more.

ris_submit_conda_env_jobBuild conda envC

Build/update a conda environment under the project's envs/ as a CPU job (never uses /home or a GPU).

Inputs: envName (required), project (required), cpus, memGb, +8 more.

ris_submit_gpu_smoke_testGPU smoke testA

Submit a tiny GPU validation job (nvidia-smi + torch CUDA check). Uses a MIG slice on general-short by default, or a full H100 on general-gpu if fullH100=true.

Inputs: project (required), dryRun, account, confirm, +2 more.

ris_submit_jupyter_jobJupyter jobB

Launch JupyterLab on a compute node and return the SSH tunnel instructions. Never opens a tunnel itself.

Inputs: project (required), gpu, cpus, port, +6 more.

ris_submit_multigpu_torch_jobMulti-GPU torch jobC

Single-node multi-GPU PyTorch training via torchrun (typed H100 by default).

Inputs: script (required), project (required), args, cpus, +14 more.

ris_submit_notebook_jobSubmit notebook jobC

Execute a project .ipynb headlessly (nbconvert) as a batch job.

Inputs: project (required), notebook (required), cpus, memGb, +13 more.

ris_submit_python_jobSubmit Python jobC

Run a project .py file as a batch job (CPU, or GPU if gpuCount>0). dryRun preview by default.

Inputs: script (required), project (required), args, cpus, +13 more.

ris_submit_r_jobSubmit R jobC

Run a project .R file via Rscript as a CPU batch job.

Inputs: script (required), project (required), args, cpus, +13 more.

ris_submit_vllm_jobvLLM server jobB

Serve a model with vLLM (OpenAI-compatible API) on a full-H100 node and return tunnel instructions.

Inputs: model (required), project (required), cpus, port, +10 more.

ris_tail_job_logsTail job logsB
Read-only

Last N lines of a job's logs plus its current state. jobId optional — defaults to your most recent job.

Inputs: jobId, lines, stream, profile, +1 more.

ris_test_key_only_authTest true key-only loginB
Read-only

Run the decisive key-only SSH test (BatchMode, no password/keyboard-interactive). Classifies whether the agent can automate without you, or whether Duo/MFA requires the multiplexing fallback.

Inputs: host, user, alias, profile, +1 more.

ris_upload_fileUpload text fileA

Write a text file into a safe project subdirectory (src/ data/ configs/ sbatch/ envs/ manifests/). Refuses overwrite unless overwrite=true. Binary content is not supported.

Inputs: content (required), project (required), relPath (required), profile, +1 more.

ris_validate_configValidate RIS configA
Read-only

Check the current profile against RIS facts: username set, account/workspace configured, partitions valid.

Inputs: profile.

ris_worker_cancelCancel a worker runB

Ask the worker to cancel a queued/submitted run (appends a cancel request).

Inputs: id (required), jobId, profile.

ris_worker_enqueueEnqueue a worker runB

Queue a Python job for the per-user worker to submit (so the agent need not stay connected). Builds and validates the sbatch script, then appends a request to the worker queue.

Inputs: script (required), project (required), cpus, memGb, +4 more.

ris_worker_statusWorker run statusC
Read-only

Read the status of a worker-queued run by its id.

Inputs: id (required), profile, project.

ris_write_ssh_configWrite SSH config blockA
Destructive

Write the managed config block to ~/.ssh/config (atomic, backed up). Requires confirm=true.

Inputs: host, user, alias, confirm, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 53 tools

    Disambiguation3/5

    The set has many well-described but overlapping tool clusters: ris_run wraps ris_submit_python_job; planning is split across ris_plan_run, ris_researcher_wizard, ris_estimate_resources, and ris_generate_sbatch_template; environment building appears in both ris_ensure_env and ris_submit_conda_env_job; job diagnostics overlap among ris_explain_job, ris_analyze_efficiency, and ris_compare_runs. Detailed descriptions help, but an agent must still disambiguate among similar submission, planning, and worker tools.

    Naming Consistency4/5

    All tools use a consistent ris_ prefix and lower_snake_case, with a strong verb_noun pattern for most names such as ris_submit_python_job, ris_cancel_job, and ris_list_my_jobs. A few deviate into noun phrases or bare verbs (ris_run, ris_job_history, ris_gpu_status), but the overall convention is predictable.

    Tool Count1/5

    53 tools is an extreme mismatch for a single MCP server, exceeding the 50+ anchor and the 25+ 'too many' threshold. Even for a broad HPC workflow, the surface is bloated with wrapper, variant, setup, and worker-specific tools that could be consolidated.

    Completeness5/5

    The server covers a remarkably complete HPC lifecycle: SSH/auth setup, profile discovery, partition/GPU inspection, project and file management, job planning, many job submission types, job control, logs, environment management, efficiency analysis, pipelines, and worker-based execution. No obvious core operation is missing for the stated RIS/Slurm domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • qzcli

      tianyilt
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables managing OpenI platform resources (login, query nodes, submit jobs, view logs) via natural language in Claude or Codex, following a kubectl/docker-style CLI.
      146
      MIT