Skip to content

Model Context Protocol (MCP)#

The Model Context Protocol (MCP) can be used to connect AI applications to data sources, tools and workflows. With the rise of coding agents and LLM-assistent working, we see the need for such a protocol endpoint for our users.

The provided MCP server has some knowledge about our systems embedded for e.g. writing proper SLURM batch scripts or how to work with the provided filesystems.

The MCP server provides some tools which results it might also be able to achieve differently. For example, if deletion of files is not allowed by the configuration, the LLM might write a Python script that deletes the files. The MCP server runs under the users' account, so whatever the user can do manually, is also allowed to the LLM. The MCP server provides just a clear interface for the coding agents but is no sandbox.

AGENTS.md file#

We provide an AGENTS.md file and a SKILL.md file that you can add to your project workspace for LLMs to work with/for our systems. It can be used in combination with the MCP server.

Using the remote MCP server#

You can run the MCP server on a cluster frontend node (or compute node) and access it from your local machine through coding agent by creating a port forwarding from your local machine to the corresponding remote server via SSH. When using the MCP server on a compute node, the common limitations apply (fewer headers, IPv4 access via proxy server, etc.).

For details see Setup port forwarding to a cluster frontend or node. The steps are:

  1. Login to the cluster frontend or start a job on the compute node you want to start the MCP server on.

  2. Obtain the fully qualified domain name (FQDN) of the machine you logged in/got a job, further on called remote server:

    hostname
# output can look like one of the following lines:
# <name>.nhr.fau.de
# <name>.rrze.fau.de
# <name>.rrze.uni-erlangen.de

  3. Start the MCP server on the remote server, it will listen on a UNIX socket. It will print out the SSH command to be executed on your local machine:

    module load nhr-fau-cluster-mcp
mcp-slurm-server

  4. Look for the line ssh -N -L <local port>:/run/user/XXXXX/nhr_fau_cluster_mcp-YYYYYY.sock <account>@<name> and copy it.

  5. On your local machine create a port forwarding to the remote machine. This will allow accessing the remote MCP server running on <remote server> through configuring the coding agent to http://localhost:<local port>/mcp:

    ssh -N -L <local port>:/run/user/XXXXX/nhr_fau_cluster_mcp-YYYYYY.sock <account>@<name>
    • <local port> must be replaced by a port number from the range of 1025 and 65535 that is currently unused on your local system.
    • <remote server> has to be replaced by FQDN of the remote server from step 2.

  6. Configure the coding agent

    OpenCode (Configuration file ~/.config/opencode/opencode.json) 
    {
  "mcp": {
    "<myname>": {
      "type": "remote",
      "url": "http://127.0.0.1:<local-port>/mcp"
    }
  }
}
    Claude Desktop

    The file is claude_desktop_config.json:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Easiest on either: Claude menu → Settings… → Developer → Edit Config, which creates the file if it does not exist and opens it. (Claude's documentation gives no path for Linux.)
    {
  "mcpServers": {
    "<myname>": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:<local-port>/mcp", "--allow-http"]
    }
  }
}
    VSCode (Configuration file .vscode/mcp.json in your workspace) 
    {
  "servers": {
    "<myname>": {
      "type": "http",
      "url": "http://127.0.0.1:<local-port>/mcp"
    }
  }
}
    Codex (Configuration file ~/.codex/config.toml)

    Codex reads MCP servers from ~/.codex/config.toml. Either add the server with the CLI:

    codex mcp add nhr_fau_cluster_mcp --url http://127.0.0.1:<local-port>/mcp

    or put it in the file yourself:

    [mcp_servers.nhr_fau_cluster_mcp]
url = "http://127.0.0.1:<local-port>/mcp"

    Check it with codex mcp list (or /mcp inside a running session). The tunnel must be up before you start Codex. Codex's documentation only shows https:// URLs; if your version refuses the plain-http loopback URL, use the same bridge as for Claude Desktop instead:

    [mcp_servers.nhr_fau_cluster_mcp]
command = "npx"
args = ["mcp-remote", "http://127.0.0.1:<local-port>/mcp", "--allow-http"]

    A project-local .codex/config.toml with the same format can hold servers for just one repository; Codex only loads it for projects you have marked as trusted.

  7. Start up your coding agent.

Supported operations#

Some operations might be disabled by the system administrators

User configuration#

Users can restrict the MCP server to use specific tools or only be able to read some paths. While the main configuration is done by the system administrators, users can refine it.

The MCP server looks for the user configuration at ~/.config/nhr_fau_cluster_mcp/config.json.

Configure file system access#

User can restrict the MCP server to use its file operations only in some base directories that are within directories allowed by the admin configuration. Furthermore, sometimes allowed directories may contain files or folders that should not be readable through the MCP. Examples for this are license files, access tokens (like SSH keys) and other security relevant files. Access to ~/.ssh is commonly denied already in the admin configuration. Some directories have a special name and the admin configuration often contains already the mapping for the known filesystems like $HOME, $WORK and $HPCVAULT. Users can specify own mappings.

{
  "files": {
    "allowedBaseDirs": ["/home/myuser/projects"],
    "deniedPaths": ["/home/myuser/projects/scratch-output"],
    "namedDirs": { "PROJECT": "/home/myuser/projects" }
  }
}

Deny specific operations#

Users can deny operations ("tools" in the MCP world) that are generally allowed by the admin configuration.

{
  "disabledTools": ["run_command"]
}
Available tools are listed here

submit_job, run_job, watch_job, list_watches, get_watch, list_jobs, job_status, cancel_job, tail_output, cluster_status, account_info, get_quota, disk_usage, read_file, write_file, edit_file, read_file_chunk, write_file_chunk, list_dir, search_files, delete_file, make_dir, delete_dir, run_command, search_docs, module_avail, module_list, module_show, module_whatis, run_with_modules, workspace_allocate, workspace_find, workspace_list, workspace_extend, workspace_release, python_list_envs, python_create_env, python_run, python_install_packages, python_delete_env, apptainer_build, apptainer_run, apptainer_exec, apptainer_pull, apptainer_inspect, job_attach

Adding own module trees#

If you manage an own module tree or want to use other users' published tree, the user can add them to the user configuration

{
  "modules": { "useDirs": ["/home/myuser/.modulefiles"] }
}