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.
Run FDS, OpenFOAM, CalculiX and other engineering simulations on cloudHPC from your AI assistant.
2026-11-16
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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.
"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
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 (asks for confirmation)
open_remote_desktop
Browser remote-desktop link of a running job
list_storage, list_results
Browse your storage and result archives
download_results ¹
Download result archives and extract them locally
get_upload_link, get_download_link
Temporary links to upload/download single files
delete_storage
Delete a file or folder (asks for confirmation)
api_usage
API rate limits and calls used
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):
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:
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.
$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:
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.
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):
(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).