How do I install CloudHPC?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does CloudHPC need an API key?

No required environment variable is listed on this record.

When was CloudHPC last checked?

Last checked 2026-11-07. Run FDS, OpenFOAM, CalculiX and other engineering simulations on cloudHPC from your AI assistant.

CloudHPC MCP server

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, 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:

"How do I prepare an OpenFOAM case for cloudHPC?" (no account needed)
"List my last simulations and summarise their status."
"Why did my last simulation fail? Check the log."
"Which vCPU and RAM type should I use for an FDS model with 8 meshes and 2 million cells?"
"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

Tool	What it does
`inspect_case` ¹	Detect solver and model size of a local folder (FDS meshes/MPI groups, OpenFOAM cells, CalculiX nodes, ...) and run pre-flight checks
`suggest_resources`	vCPU and RAM type recommendation, with reasoning
`solver_guide`	How to prepare a case for a solver: input files, what cloudHPC does automatically, restart, optional settings, parallelism, logs
`list_solvers`, `list_machine_options`	Available solvers, vCPU counts and RAM types
`upload_folder` ¹	Compress a local case folder and upload it to your storage
`launch_simulation`	Launch a run (asks for confirmation)
`list_simulations`, `get_simulation`, `wait_for_simulation`	Follow your runs; finished runs include a diagnosis of known errors
`sync_simulation`	Upload partial results of a running job
`stop_simulation`	Soft or hard stop (asks for confirmation)
`resume_simulation`	Resume a stopped run with the same solver, vCPU, RAM type and folder (FDS and OpenFOAM; asks for confirmation)
`start_desktop`	Start a Linux or Windows remote desktop for post-processing; billed until you stop it (asks for confirmation)
`live_settings`	What can be changed in a running simulation, the current content of those files and the state of previous live updates
`update_running_simulation`	Change a running simulation without stopping it: OpenFOAM `system/controlDict`, `fvSolution`, `fvSchemes`; FDS `<CHID>.stop`; code_saturne `RESU/<run>/control_file`; OpenRadioss/OpenCourant `<root>_0001.ctl`. The files go to the `_push` folder of the case and a sync is requested automatically, so the machine applies them within a few minutes ()

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.

Assistant	Desktop app	Terminal (Linux)	Web app
Claude	Claude Desktop (Windows, macOS, Linux beta)	Claude Code	claude.ai (custom connector)
ChatGPT	ChatGPT desktop app (where MCP servers are available)	Codex CLI	ChatGPT (OAuth sign-in)
Gemini	not supported: no Gemini desktop app with MCP support	Gemini CLI	Gemini (OAuth sign-in)
GitHub Copilot	VS Code (Copilot agent mode)	Copilot CLI	not supported

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 <key>). 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 upload it from the cloudHPC web app.
To get results, ask for a download link (get_download_link).

Sign-in with OAuth

When you add the connector with OAuth, the assistant opens a cloudHPC sign-in page:

Check the name of the app asking for access. It will be able to see your simulations and storage, upload files and launch or stop simulations, which are billed to your account.
Paste your API key (how to find your API key).
Optionally tick Read-only access: the assistant can then see simulations, storage and results, but cannot launch, stop, resume, upload, delete or open remote desktops. Useful to try the connector safely, or for colleagues who only need to follow the runs.
Click Connect.

The assistant never sees the key: it receives tokens that expire after one hour and are renewed automatically for 30 days, then you sign in again. To revoke access for every connected assistant, regenerate the API key in your cloudHPC profile: access stops within an hour.

claude.ai

On plans with custom connectors: Settings > Connectors > Add custom connector, URL https://mcp.cloudhpc.cloud/mcp, then either:

leave the authentication on OAuth and sign in when asked (Sign-in with OAuth), or
choose No sign-in and under Request headers add X-API-Key = your-api-key.

Enable the connector in a conversation from the tools menu. The same connector is also available in the Claude desktop and mobile apps.

ChatGPT web

In ChatGPT, turn on developer mode and add a custom connector (app):

URL: https://mcp.cloudhpc.cloud/mcp
Authentication: OAuth

Then sign in on the cloudHPC page (Sign-in with OAuth).

Gemini web

In the Gemini app (gemini.google.com):

Click Customise in the left sidebar.
Open the Connectors tab.
Click + Custom, enter the URL https://mcp.cloudhpc.cloud/mcp and click Next.
Sign in on the cloudHPC page that opens (Sign-in with OAuth).

Gemini registers itself automatically: you do not need an OAuth client ID or secret. The connector then appears under Connected apps.

Copilot web

Microsoft Copilot and Copilot Chat on github.com do not support custom MCP servers.

Other clients using the hosted endpoint

Any MCP client that supports streamable HTTP with custom headers works, for example:

claude mcp add --transport http cloudhpc https://mcp.cloudhpc.cloud/mcp \
  --header "X-API-Key: your-api-key"

{ "mcpServers": { "cloudhpc": {
    "httpUrl": "https://mcp.cloudhpc.cloud/mcp",
    "headers": { "X-API-Key": "your-api-key" } } } }

(the second is the Gemini CLI format; VS Code uses "type": "http", "url" and "headers"; Codex CLI uses url and http_headers in config.toml).

Good to know

Upload layout: the content of the case folder is archived at the root of upload.tar.gz and uploaded into a storage folder with the same name as the local folder. Hidden files are skipped. Folder names must not contain , ( ) ' $ ~ " # or spaces.
Resources: FDS, CalculiX and code_aster start on highcpu; after a memory error move to standard, then highmem. OpenFOAM and other MPI-only solvers use highcore or hypercore. 1 vCPU on highcpu is never suggested for a solver: it has too little RAM to start.
Checking runs: a run can end as COMPLETED even if the solver failed. When a run ends the server scans its output for the errors listed in the errors guide and suggests the fix; after downloading, it also checks the solver's own logs (OpenFOAM log.*, FDS .out).
Costs are billed per vCPU-hour and shown in euro when a run ends.
Storage: files are deleted automatically 60 days after creation. Download your results.
Rate limits: 100 API calls/hour on free accounts, 500 on full accounts (no daily limit). The server reads the rate-limit headers and stops before exceeding them.
Your data: what the tools return (simulation names, logs, file lists, costs) is sent to the AI provider of the assistant you use, under your own account and its terms. For confidential projects check your provider's data settings (e.g. training opt-out, business plans). With the local installation your API key stays on your computer; the hosted endpoint only forwards it and stores nothing. With OAuth sign-in the assistant only holds encrypted, expiring tokens, not the key.

Troubleshooting

Problem	Fix
The assistant does not see the cloudHPC tools	Restart the app after editing its configuration; in terminal apps check with `/mcp` or `mcp list`.
`command not found` / server fails to start	Use the full path of `cloudhpc-mcp` (`which cloudhpc-mcp`). Desktop apps do not load your shell's PATH, conda or virtual environments.
`Unauthorized: the API key is invalid`	Copy the key again from your cloudHPC profile page.
Hosted endpoint: `Invalid header name`	Write the header exactly as `X-API-Key: your-api-key` (name, colon, space, key).
Sign-in page: "The API key was not accepted"	Copy the key again from your profile (how to find it); paste only the key, without spaces.
The assistant asks for an OAuth client ID and secret	Remove the connector and add it again with the URL `https://mcp.cloudhpc.cloud/mcp`: it registers automatically, no client ID or secret is needed.
The assistant asks you to sign in again	Normal after 30 days, or after you regenerated the API key: sign in with the current key.
`rate limit reached`	Wait for the next hour, or ask the assistant to check less often.
The wait for a run is cut off	Raise the tool timeout of your client (see the examples above) or ask the assistant to wait in shorter steps.

Development

git clone https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp
cd cloudhpc-mcp
pip install -e ".[test]"
pytest            # offline tests with a mocked API

Server modes (CLOUDHPC_MCP_MODE):

Mode	Transport	Use
`local` (default)	stdio	Desktop and terminal apps on your computer
`remote`	streamable HTTP	Hosted endpoint; the API key comes with each request
`remote` + OAuth	streamable HTTP	Set `CLOUDHPC_OAUTH_SECRET` (random value; comma-separated list to rotate) and `CLOUDHPC_PUBLIC_URL` (public base URL): adds OAuth 2.1 sign-in (PKCE, dynamic client registration and client ID metadata documents) where the user pastes the API key on a server page; tokens are encrypted, nothing is stored. Requests without credentials get `401` with the OAuth challenge; `X-API-Key` keeps working
`public`	streamable HTTP	Key-less guide endpoint (e.g. for a website chat bot): only `solver_guide`, `list_solvers`, `list_machine_options`, `suggest_resources`. The solver and machine catalog is read with the key in `CLOUDHPC_CATALOG_APIKEY` (a dedicated account with no data) and cached for `CLOUDHPC_CATALOG_TTL` seconds (default 3600); requests are limited to `CLOUDHPC_PUBLIC_RATE_PER_MIN` per client IP (default 60)

scripts/e2e_test.py runs the whole workflow against the real API with your account: it uploads a tiny FDS case and, with --confirm-costs, runs it on 1 vCPU for about a minute (--no-launch only uploads; --cleanup deletes the test folder at the end).

Support

Documentation: https://docs.cloudhpc.cloud
Issues: https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp/issues

License

Apache-2.0

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install CloudHPC?

Does CloudHPC need an API key?

What transport does CloudHPC use?

When was CloudHPC last checked?

Documentation

cloudHPC MCP server

What you can ask

Safe first prompts

Tools

Installation

Connect your AI assistant

Claude

Claude Desktop

Claude Code

ChatGPT / Codex

ChatGPT desktop app

Codex CLI

Gemini

Gemini CLI

GitHub Copilot

VS Code (Copilot agent mode)

Copilot CLI

Other MCP clients

Web apps (hosted endpoint)

Sign-in with OAuth

claude.ai

ChatGPT web

Gemini web

Copilot web

Other clients using the hosted endpoint

Good to know

Troubleshooting

Development

Support

License