AI Interfaces for Chimera

AI agents are a powerful technology of the future which enables to combine high-level abstraction with low-level tools. We encourage you to learn as much about it as possible.

• Employing AI agents allows you to control the Chimera cluster using natural language.
• For an introduction into the applications and dangers of agentic tools on Chimera, please look at the recording from our HPC and RSE workshop.
• Remember that any actions the agent takes are still your personal responsibility.

This page describes the interfaces you drive from an AI client running on your own computer, which connects to Chimera over SSH. If you would rather open a complete research application in your browser from a JupyterHub session, see Agentic platforms for research instead, which covers Biomni Web and Claude Science.

WARNING: Giving your AI agent an unrestricted access to the cluster directly via command line is possible but not recommended. By doing that the agent has the same level of access to all the files on the cluster like you and can perform irreversible changes to them, kill and submit jobs without your knowledge, etc. In general, "soft limits" in the form of instructions for the agent are never 100% reliable and many examples of agent's failures exist. Agentic safety is an area of rapid research and development.

To mitigate the risks associated with the use of agents, we recommend the following:

• Use one of the agentic interfaces specifically tailored for the Chimera cluster, described below.
• Watch out for the trainings offered by the RSE team on the topics of AI assisted programming and agentic workflows. The University's AI team offers further guidelines and trainings on AI for teachers and students.

Choosing an interface

The Model Context Protocol (MCP) allows AI clients such as Codex, Gemini, Claude Code, and OpenCode to use tools provided by external processes. Chimera currently has two MCP-based AI-on-cluster projects, but they serve different purposes:

ChimeraMCP

ChimeraMCP lets MCP-capable AI agents operate on Chimera through guarded Slurm and archive tools. Instead of giving a model raw shell access, you connect it to typed MCP servers that run on Chimera under your Unix account.

The companion ChimeraMCP OpenCode HPC Agent repository provides ready-made OpenCode agent, subagent, and configuration templates for using ChimeraMCP from OpenCode.

ChimeraMCP currently ships two MCP servers through the administrator-managed chimera-mcp module:

• chimera-slurm, started by chimera-slurm-mcp, for Slurm queue inspection, job submission, job logs, accounting, quotas, software module lookup, and user-scoped workspace file operations.
• chimera-filecompress, started by chimera-filecompress-mcp, for archive planning, creation, and extraction for zip, tar, tar.gz, tar.bz2, and tar.xz.

Warning

An MCP-connected model can act on your behalf through the tools you expose to it. With ChimeraMCP, that can include reading and writing files in the configured work area, submitting jobs, canceling or updating your jobs when those tools are enabled, moving files, creating or extracting archives, and reading job logs.

Anything returned by the server can also be shown to the connected AI service, including file paths, log contents, job metadata, error messages, and snippets of your data. Do not connect ChimeraMCP to a model or provider you do not trust, and do not ask the agent to handle secrets, passwords, tokens, private keys, or sensitive data you are not allowed to share.

ChimeraMCP adds guardrails, but it is not a security sandbox. You remain responsible for your files, jobs, resource usage, and compliance with Chimera site policy.

Prerequisites

Normal users do not install ChimeraMCP locally and do not need to clone the ChimeraMCP repository. The standard setup is the shared Chimera module:

module load chimera-mcp

You need:

• A Chimera account and SSH access, usually USER@hpc.troja.mff.cuni.cz.
• Access to the shared chimera-mcp module on Chimera.
• A writable Chimera work area. In the standard configuration, the user-facing data root is /work/$USER, derived from /work/MCP_scripts and /work/MCP_logs.
• A local MCP-capable client, such as Codex, Gemini, Claude Code, or OpenCode.

Your local client starts each MCP server over SSH. Replace USER@hpc.troja.mff.cuni.cz with your Chimera login. Configure key-based SSH authentication before using BatchMode=yes, because MCP clients cannot answer an interactive password prompt from an MCP subprocess.

Check the installation

Log in to Chimera and confirm that the module exposes both commands:

ssh USER@hpc.troja.mff.cuni.cz
module load chimera-mcp
which chimera-slurm-mcp
which chimera-filecompress-mcp

Connect your model

Configure both servers as separate stdio MCP servers. Keep the remote bash -lc 'module load chimera-mcp && exec ...' command as one SSH argument.

[mcp_servers.chimera-slurm]
command = "ssh"
args = [
  "-T",
  "-o", "BatchMode=yes",
  "-o", "LogLevel=ERROR",
  "USER@hpc.troja.mff.cuni.cz",
  "bash -lc 'module load chimera-mcp && exec chimera-slurm-mcp'"
]

[mcp_servers.chimera-filecompress]
command = "ssh"
args = [
  "-T",
  "-o", "BatchMode=yes",
  "-o", "LogLevel=ERROR",
  "USER@hpc.troja.mff.cuni.cz",
  "bash -lc 'module load chimera-mcp && exec chimera-filecompress-mcp'"
]

{
  "mcpServers": {
    "chimera-slurm": {
      "command": "ssh",
      "args": [
        "-T",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "USER@hpc.troja.mff.cuni.cz",
        "bash -lc 'module load chimera-mcp && exec chimera-slurm-mcp'"
      ],
      "timeout": 600000,
      "trust": true
    },
    "chimera-filecompress": {
      "command": "ssh",
      "args": [
        "-T",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "USER@hpc.troja.mff.cuni.cz",
        "bash -lc 'module load chimera-mcp && exec chimera-filecompress-mcp'"
      ],
      "timeout": 600000,
      "trust": true
    }
  }
}

claude mcp add --scope user --transport stdio chimera-slurm -- \
  ssh -T -o BatchMode=yes -o LogLevel=ERROR USER@hpc.troja.mff.cuni.cz \
  "bash -lc 'module load chimera-mcp && exec chimera-slurm-mcp'"

claude mcp add --scope user --transport stdio chimera-filecompress -- \
  ssh -T -o BatchMode=yes -o LogLevel=ERROR USER@hpc.troja.mff.cuni.cz \
  "bash -lc 'module load chimera-mcp && exec chimera-filecompress-mcp'"

claude mcp list

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chimera-slurm": {
      "type": "local",
      "command": [
        "ssh",
        "-T",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "USER@hpc.troja.mff.cuni.cz",
        "bash -lc 'module load chimera-mcp && exec chimera-slurm-mcp'"
      ],
      "enabled": true,
      "timeout": 600000
    },
    "chimera-filecompress": {
      "type": "local",
      "command": [
        "ssh",
        "-T",
        "-o", "BatchMode=yes",
        "-o", "LogLevel=ERROR",
        "USER@hpc.troja.mff.cuni.cz",
        "bash -lc 'module load chimera-mcp && exec chimera-filecompress-mcp'"
      ],
      "enabled": true,
      "timeout": 600000
    }
  }
}

opencode mcp list

Restart your AI client after changing MCP configuration. If the remote shell cannot find module, your site may need to source its Lmod initialization script before module load chimera-mcp. See the ChimeraMCP documentation for the deployment and troubleshooting reference.

Optional agent skills

ChimeraMCP also provides optional agent skill bundles. Skills are reusable instruction packages for AI clients; they are not MCP servers, they do not install ChimeraMCP, and they do not replace the MCP server configuration above. Use them when your client supports skills and you want the model to load Chimera-specific workflow guidance on demand.

Included skills:

• chimera-slurm-mcp: live and managed Slurm workflows through Chimera Slurm MCP, including queue inspection, owned-job logs, accounting, failure diagnosis, workspace files, and guarded submissions.
• chimera-filecompress-mcp: archive planning, creation, extraction, protected-root handling, and Slurm routing for large archive work through Chimera FileCompress MCP.
• chimera-cluster: general Chimera guidance outside MCP-managed workflows, such as SSH, JupyterHub, storage, modules, manual Slurm, GPUs, and Apptainer.
• chimera-mcp-server-authoring: developer guidance for adding or reshaping ChimeraMCP servers so they follow the repository conventions.

Copy the whole skill directory, not only SKILL.md, because bundled references and assets are part of the skill behavior. From a ChimeraMCP checkout:

mkdir -p ~/.codex/skills ~/.gemini/skills ~/.claude/skills
cp -R skills/chimera-cluster skills/chimera-mcp-server-authoring skills/chimera-slurm-mcp skills/chimera-filecompress-mcp ~/.codex/skills/
cp -R skills/chimera-cluster skills/chimera-mcp-server-authoring skills/chimera-slurm-mcp skills/chimera-filecompress-mcp ~/.gemini/skills/
cp -R skills/chimera-cluster skills/chimera-mcp-server-authoring skills/chimera-slurm-mcp skills/chimera-filecompress-mcp ~/.claude/skills/

Restart the AI client after installing or updating skills so it reloads the skill metadata.

What ChimeraMCP can do

All ChimeraMCP tools return the same response envelope:

{"ok": true, "data": "..."}

or:

{"ok": false, "error_code": "...", "message": "..."}

Use chimera-slurm to inspect current cluster state and software modules:

• current partitions and node state
• cached Lmod module search and module details
• user Slurm associations and disk quotas

Use chimera-slurm to inspect your jobs and the live cluster queue:

• slurm_list_jobs lists jobs owned by the current Unix user.
• slurm_list_all_jobs gives a read-only live view of the whole queue.
• array tools summarize and inspect array job tasks.

Owned-job detail tools can read job metadata, accounting, efficiency, stdout and stderr logs, and structured failure diagnoses.

Use chimera-slurm to submit work through guarded paths:

• built-in templates with slurm_list_templates and slurm_submit_template_job
• stored custom scripts
• project scripts under the configured user data root
• managed DMTCP checkpoint/restart for custom and project scripts
• advanced user-managed DMTCP tools for scripts that intentionally contain DMTCP logic

The active security level may hide custom, project, DMTCP, or control tools. Template submission does not support DMTCP in v1.

When enabled by policy, chimera-slurm can cancel or update jobs owned by the server user. It does not allow controlling other users' jobs.

The Slurm server can also operate on files and directories under the configured user data root, normally /work/$USER in the standard deployment. These tools are intended for job inputs, small generated notes, scripts, logs, and workflow artifacts. They do not provide unrestricted filesystem access.

Use chimera-filecompress for archive work:

• plan archive creation or extraction before doing it
• create zip, tar, tar.gz, tar.bz2, and tar.xz archives
• safely extract supported archive formats
• reject plain relative paths, unsafe archive members, and protected-root access
• auto-rename outputs rather than overwrite existing paths
• route large archive operations through Slurm using the FileCompress_job template

FileCompress accepts absolute paths and ~/ paths. Filesystem permissions still apply.

Safe use

Start with read-only requests when connecting a new model. Before submitting, canceling, updating, extracting, or moving data, ask the agent to show the exact planned action, target paths, job inputs, Slurm overrides, and expected outputs.

Good first prompts:

Use Chimera Slurm MCP to list my running and pending jobs.

Use Chimera Slurm MCP to summarize current partitions, quotas, and my Slurm associations.

Use Chimera FileCompress MCP to plan creating ~/project.tar.gz from ~/project.

The complete server reference, configuration rules, and security model are maintained in the ChimeraMCP documentation.

ChimeraSandbox (experimental)

ChimeraSandbox runs a small MCP server inside a persistent Apptainer instance on a Slurm compute node. It gives an OpenCode agent four tools:

The submitted project directory is mounted at /workspace, which is the intended location for inputs, environments, checkpoints, logs, and results. Container state and background processes survive OpenCode reconnects while the Slurm job remains alive. Only data stored on a persistent host filesystem, including the mounted /workspace, survives the end of the allocation.

This workflow is experimental. Unlike ChimeraMCP, its bash and file tools do not enforce guarded Slurm, path, or owned-job policies. Commands run with the permissions of your cluster account, and /workspace contains real user data. Review requested operations accordingly.

Add ChimeraSandbox to OpenCode

Start the ChimeraSandbox Slurm job and Apptainer instance yourself, using the instructions in the ChimeraSandbox repository. The GitLab project path is still rse/projects/apptainermcp.git; the user-facing project name is ChimeraSandbox.

Build the image on a compute node, not on the login node:

git clone git@gitlab.mff.cuni.cz:rse/projects/apptainermcp.git ChimeraSandbox
cd ChimeraSandbox
./scripts/build_submit.sh --output ~/chimera_sandbox.sif

Then start a sandbox allocation. On the current Chimera configuration, GPU jobs use the gpu-ffa partition; use sinfo if you need to verify partition names live:

mkdir -p ~/chimera-sandbox-test
./scripts/submit.sh \
  --mount ~/chimera-sandbox-test \
  --image ~/chimera_sandbox.sif \
  --partition gpu-ffa \
  --gres mps:5 \
  --time 01:00:00 \
  --user USER \
  --login hpc.troja.mff.cuni.cz

When the job is running, note its Slurm job ID. You can get it from the submission output or with:

squeue --me

Then add a chimera-sandbox entry to the mcp object in your global or project OpenCode configuration. Replace USER with your Chimera login and JOBID with the running Slurm job ID:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chimera-sandbox": {
      "type": "local",
      "enabled": true,
      "command": [
        "ssh", "-T", "USER@hpc.troja.mff.cuni.cz",
        "srun", "--jobid=JOBID", "--overlap",
        "apptainer", "exec", "instance://chimerasandbox",
        "python", "-u", "/opt/mcp/server.py"
      ]
    }
  }
}

Restart OpenCode and check the connection with opencode mcp list. A useful first request is to run hostname, nvidia-smi, pwd, and python --version through the sandbox bash tool. We verified this flow on Chimera with a running chimera-sandbox MCP server, /workspace bind mount, Python/R/mamba/git, and an NVIDIA L40 visible inside the container.

Closing or restarting OpenCode does not release the Slurm allocation. The requested CPUs, memory, and GPU remain reserved until the job reaches its wall-time or is canceled. When finished, remove or disable the stale OpenCode entry and release the resources:

scancel JOBID