cloudHPC

cloudHPC MCP server

Run engineering simulations on cloudHPC from AI assistants that support the Model Context Protocol (MCP): Claude, ChatGPT/Codex, Gemini, GitHub Copilot and others, from their desktop apps, terminal apps and, where supported, web apps. Inspect a local case, get vCPU/RAM advice, upload the folder, launch, monitor, diagnose errors and download the results, all from a conversation.

Supported solvers: everything available on cloudHPC (FDS, OpenFOAM, snappyHexMesh, DAFoam, code_aster, CalculiX, OpenRadioss/OpenCourant, SU2, openTELEMAC, LIGGGHTS, LAMMPS, Kratos Multiphysics, OpenLB, Palabos, FreeFEM, T-Flows, DualSPHysics, preCICE coupled OpenFOAM/CalculiX/code_aster, EnergyPlus, CONTAM, ...). Resource advice follows the cloudHPC scalability rules and run diagnosis follows the cloudHPC errors guide.

• What you can ask
• Safe first prompts
• Tools
• Installation
• Connect your AI assistant
• Claude · ChatGPT / Codex · Gemini · GitHub Copilot · Other clients
• Web apps (hosted endpoint)
• Good to know
• Troubleshooting

What you can ask

• *"Check the FDS case in this folder and tell me which resources to use."*
• *"Run it on cloudHPC and download the results when it finishes."*
• *"What is the status of my running simulations?"*
• *"My last run failed: what went wrong?"*
• *"My OpenFOAM run is converging well: extend endTime to 2000 without stopping it."*

Safe first prompts

Start with questions that only read data, then move on to actions that cost money once you are comfortable with how the assistant works:

1. *"How do I prepare an OpenFOAM case for cloudHPC?"* (no account needed)
2. *"List my last simulations and summarise their status."*
3. *"Why did my last simulation fail? Check the log."*
4. *"Which vCPU and RAM type should I use for an FDS model with 8 meshes and 2 million cells?"*
5. *"What is in the storage folder of my last run, and which files are results?"*

Only then: *"Upload this case and launch it"*, *"Resume simulation 1234"*. Every action that costs money or deletes data asks for your confirmation first, and the assistant shows you what it will do. With OAuth sign-in you can also connect with read-only access (see Sign-in with OAuth).

Tools

Actions that cost money or delete data (launching a run, a hard stop, deleting from storage) always need your confirmation. In apps that support it (e.g. Claude Code) the server shows you a confirmation dialog directly, so the assistant cannot confirm on your behalf; in other apps the assistant shows you a summary and waits for your OK.

¹ Only with the local installation: they work on files on your computer. In web apps (hosted endpoint) use get_upload_link / get_download_link instead.

Installation

Requirements:

• Python 3.10 or newer
• A cloudHPC account and its API key: open your cloudHPC profile page (APIKEY docs). The key gives full access to your account: keep it private.

Install with pipx (recommended: isolated, and the command ends up in ~/.local/bin, easy to find for desktop apps):

pipx install git+https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp

or with pip:

pip install git+https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp

This installs the cloudhpc-mcp command. Find its full path, you may need it below:

which cloudhpc-mcp          # Linux / macOS

where cloudhpc-mcp # Windows

The API key is read from the CLOUDHPC_APIKEY environment variable or, if that is not set, from the file ~/.cfscloudhpc/apikey created by cloudHPCexec.

Connect your AI assistant

There are two ways to connect:

• Local installation (desktop and terminal apps): the server runs on your computer, so it can read your case folders and save results next to them. All tools are available. Recommended.
• Hosted endpoint (web apps): https://mcp.cloudhpc.cloud/mcp, nothing to install. You connect by signing in once with your API key (OAuth) or by sending the key in a header. It cannot read files on your computer: you upload cases and download results with temporary links (or from the cloudHPC web app). See Web apps.

In every example replace your-api-key with your key. If the assistant cannot find the cloudhpc-mcp command, write its full path instead (see Installation).

Claude

Claude Desktop

Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: use Edit Config to open the file

{

"mcpServers": { "cloudhpc": { "command": "cloudhpc-mcp", "env": { "CLOUDHPC_APIKEY": "your-api-key" } } } }

Restart Claude Desktop. The cloudHPC tools appear in the tools menu of a new conversation.

Claude Code

claude mcp add --scope user cloudhpc -e CLOUDHPC_APIKEY=your-api-key -- cloudhpc-mcp

--scope user makes it available in every folder. Check it with claude mcp list or /mcp inside Claude Code.

ChatGPT / Codex

ChatGPT desktop app

In recent versions of the ChatGPT desktop app: Settings > MCP servers > Add server, choose STDIO:

• Command: cloudhpc-mcp
• Environment variable: CLOUDHPC_APIKEY = your-api-key

The app shares its MCP configuration with Codex (~/.codex/config.toml, see below), so a server added in one is available in the other. Availability depends on app version and plan. The ChatGPT web app only supports remote connectors and cannot run this local server.

Codex CLI

codex mcp add cloudhpc --env CLOUDHPC_APIKEY=your-api-key -- cloudhpc-mcp

or edit ~/.codex/config.toml:

[mcp_servers.cloudhpc]

command = "cloudhpc-mcp" tool_timeout_sec = 1900 # wait_for_simulation can wait up to 30 minutes

[mcp_servers.cloudhpc.env] CLOUDHPC_APIKEY = "your-api-key"

Check it with codex mcp list.

Gemini

Gemini CLI

gemini mcp add -s user -e CLOUDHPC_APIKEY=your-api-key cloudhpc cloudhpc-mcp

or edit ~/.gemini/settings.json:

{

"mcpServers": { "cloudhpc": { "command": "cloudhpc-mcp", "env": { "CLOUDHPC_APIKEY": "$CLOUDHPC_APIKEY" }, "timeout": 1900000 } } }

$CLOUDHPC_APIKEY takes the key from your shell (export CLOUDHPC_APIKEY=...); timeout (milliseconds) lets wait_for_simulation wait up to 30 minutes. Check it with /mcp inside Gemini CLI.

The Gemini desktop and web apps do not support custom MCP servers.

GitHub Copilot

VS Code (Copilot agent mode)

Run MCP: Open User Configuration from the Command Palette (or create .vscode/mcp.json in a project) and add:

{

"inputs": [ { "type": "promptString", "id": "cloudhpc-key", "description": "cloudHPC API key", "password": true } ], "servers": { "cloudhpc": { "type": "stdio", "command": "cloudhpc-mcp", "env": { "CLOUDHPC_APIKEY": "${input:cloudhpc-key}" } } } }

VS Code asks for the key once and stores it securely. Open Copilot Chat in Agent mode and enable the cloudHPC tools from the tools picker.

Copilot CLI

Edit ~/.copilot/mcp-config.json:

{

"mcpServers": { "cloudhpc": { "type": "local", "command": "cloudhpc-mcp", "args": [], "env": { "CLOUDHPC_APIKEY": "your-api-key" }, "tools": ["*"] } } }

or use /mcp add inside a Copilot CLI session. The Microsoft Copilot app for Windows does not support custom MCP servers.

Other MCP clients

Configure a stdio server with command cloudhpc-mcp and the environment variable CLOUDHPC_APIKEY.

Web apps (hosted endpoint)

Endpoint: https://mcp.cloudhpc.cloud/mcp (streamable HTTP). Two ways to authenticate:

• Sign in with OAuth (ChatGPT, Gemini, claude.ai and any client that supports OAuth for MCP servers): see Sign-in with OAuth.
• API key header: the client sends your key with every request in the X-API-Key header (or Authorization: Bearer ). The endpoint stores nothing: the key is only forwarded to the cloudHPC API for that request.

What changes compared with the local installation:

• inspect_case, upload_folder and download_results are not available: the hosted server cannot see your computer.
• To upload a case, compress the content of the case folder (files at the root of the archive) and ask the assistant for an upload link (get_upload_link): it gives you a ready curl command. Or upl