gpu-bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GPU_BRIDGE_RENDEZVOUS_URL | No | Set this to use your own relay instead of the default ntfy.sh relay for discovering new session tunnel addresses. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Runs ML work (RL, CV, LLM fine-tuning, experiments, competitions) on remote GPUs: Google Colab, Kaggle, and rented Hugging Face machines.
If the user asks how to set anything up, or nothing is connected yet, call
setup_guide (it returns the exact steps for each platform).
example_script returns ready-made training scripts.
Get a machine first — one of:
Kaggle (free GPU):
kaggle_runtime_start, thenconnect_runtime. Fully automatic when the user is logged in to Kaggle on this computer.Colab (free GPU):
colab_runtime_startreturns one line for the user to run in a Colab cell; when it is running,connect_runtime. Nothing is copied back.Hugging Face, interactive (rented):
hf_runtime_start(flavor)thenhf_runtime_connect. It bills per minute:hf_runtime_stopwhen done.Hugging Face, one training = one machine:
hf_job_launch(script, run_name, flavor, timeout). No runtime needed; the machine stops when the script ends.connect_runtime(no arguments) andhf_runtime_connectre-attach to a runtime that is still up, so call one at the start of every session.runtime_stopends a Colab/Kaggle session.
Then:
quick work on the runtime:
run_code, or edit a notebook withnotebook_*.training on the runtime:
launch_training(script, run_name)returns immediately — the job runs in the background. NEVER run long training viarun_code.every run (runtime or Hugging Face job) is followed the same way:
get_run_status,get_logs,get_metrics,plot_metrics,stop_run.inside a training script use the injected helpers
log_metric(step, **kv)andsave_checkpoint_file(path), and readSEED. Do not import them.results must leave the machine before it goes away:
save_checkpoint(to the local computer) orhf_push_run(to the Hugging Face Hub). Hugging Face jobs upload whatsave_checkpoint_fileis given to the Hub repo<user>/<run_name>by themselves.RL:
rl_setup,rl_reward_curve,rl_record_rollout,rl_seed_sweep.CV:
cv_load_dataset,cv_training_curves,cv_show_predictions.competitions:
kaggle_*(files, submit, submissions, leaderboard).Hub:
hf_whoami,hf_search,hf_upload,hf_download; Spaces:hf_space_*.
Money: Hugging Face machines cost real money per minute. Ask the user before renting a
GPU flavor, show prices with hf_hardware, always set a sensible timeout, and use
hf_job_list to confirm nothing is left running.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| connect_runtimeA | Connect to (or re-attach to) the runtime. Call it with no arguments in most cases. With no arguments it does the right thing: it finds the Colab/Kaggle session just
started with colab_runtime_start / kaggle_runtime_start (waiting up to
url, token: only for connecting by hand to a Jupyter server whose address and token you were given. hf_auth: with url/token, set True for a JupyterLab running in a Hugging Face Space (url "https://-.hf.space", token = the Space's JUPYTER_TOKEN). |
| runtime_statusA | Report kernel liveness, Python/CUDA info, GPU, RAM and disk on the runtime. |
| run_codeA | Execute Python on the runtime; returns stdout/results plus any PNG images. For quick, interactive work. Do NOT run long training here — it will hit the timeout. Use launch_training for anything that takes minutes. |
| upload_fileB | Upload a local file to the runtime (path is relative to the runtime's contents root). |
| download_fileC | Download a file from the runtime to the local machine. |
| fetch_imageA | Fetch an image file (png/jpg) from the runtime and show it inline. Use for prediction visualizations, Grad-CAM, rollout frames, or any figure your code saved to disk on the runtime. |
| launch_trainingA | Launch a training script as a background job on the runtime; returns immediately. The script may call the injected helpers requirements: space-separated pip packages to install first (e.g. "stable-baselines3 gymnasium"). env_json: JSON object of extra environment variables for the run. |
| get_run_statusB | Check whether a launched run is still alive and how many metric rows it has logged. |
| get_logsB | Return the last |
| get_metricsB | Return the last |
| stop_runB | Terminate a running training job (for a Hugging Face job this stops its billing). |
| list_runsA | List all training runs this MCP has launched (from the local registry). The status shown is the last one seen; get_run_status checks a run live. |
| plot_metricsB | Plot one or more metric series for a run and return the chart as an image. keys: comma-separated metric names, e.g. "loss,val_acc" or "reward". |
| save_checkpointA | Download a run's checkpoint(s) to the local machine so they survive VM shutdown. filename: a single file in the run's checkpoints/ dir; if blank, the whole checkpoints/ dir is zipped on the runtime and downloaded. For a Hugging Face job the checkpoints come from the run's Hub repo instead. |
| restore_checkpointB | Upload a locally-saved checkpoint file back into a run's checkpoints/ dir on the runtime. |
| notebook_readA | Read a notebook and list its cells with indices, types, and source previews. |
| notebook_createC | Create a new empty notebook at |
| notebook_add_cellB | Add a cell to a notebook. index=-1 appends; otherwise inserts before that index. |
| notebook_edit_cellC | Replace the source of cell |
| notebook_delete_cellC | Delete cell |
| notebook_run_cellB | Execute a notebook cell's code on the kernel; optionally write outputs back. Returns stdout/results and any images. Only 'code' cells are executed. |
| rl_setupA | Install a standard RL stack on the runtime (Gymnasium + Stable-Baselines3 + imageio). extras: Gymnasium extras to include, e.g. "classic-control", "box2d", "atari,accept-rom-license". Also installs xvfb + pyvirtualdisplay for headless rendering. |
| rl_reward_curveB | Plot the reward curve for an RL run (auto-detects reward-like metric keys). |
| rl_record_rolloutA | Render an episode and return a contact sheet of frames (and save a gif on the runtime).
|
| rl_seed_sweepA | Launch the same training script across several seeds as separate runs. seeds: comma-separated, e.g. "0,1,2". Each becomes a run '<run_name>_s'
with GPU_BRIDGE_SEED set (read it as |
| cv_load_datasetA | Download a Kaggle dataset or competition onto the runtime and unzip it. ref: "owner/dataset-slug" for datasets, or the competition slug for competitions.
kind: "dataset" or "competition".
Works when this computer is logged in to Kaggle (the login is used for this one
download and is not kept on the runtime), or on a Kaggle machine. On a session from
kaggle_runtime_start, prefer its |
| cv_training_curvesC | Plot standard CV metrics for a run (loss / accuracy / mAP / IoU — auto-detected). |
| cv_show_predictionsA | Run inference/visualization code on the runtime and show the saved image inline.
|
| kaggle_submitB | Submit a file to a competition. file: a path on this computer, or a path on the connected runtime (for example a run's submission.csv), which is fetched first. |
| kaggle_submissionsB | List your recent submissions and their scores for a competition. |
| kaggle_leaderboardC | Show the top of a competition's public leaderboard. |
| kaggle_competition_filesC | List the downloadable files for a competition. |
| kaggle_search_datasetsA | Search Kaggle datasets by keyword (returns refs usable with cv_load_dataset). |
| hf_hardwareA | List the machines Hugging Face rents for jobs, with specs and price per hour. |
| hf_job_launchA | Run a training script on its own rented Hugging Face machine; returns immediately. The machine is billed per minute and stops when the script ends, fails, or hits
flavor: machine type from hf_hardware, e.g. "t4-small", "a10g-small", "a100-large".
timeout: time limit such as "30m", "2h", "1d".
requirements: space-separated pip packages, e.g. "torch transformers peft datasets".
env_json: JSON object of extra environment variables.
image: optional Docker image that has |
| hf_job_listB | List your Hugging Face jobs. By default only those running (and billing) right now. |
| hf_job_cancelA | Cancel any Hugging Face job by id (from hf_job_list), stopping its billing. |
| hf_runtime_startA | Rent a Hugging Face machine running Jupyter, to use like a Colab/Kaggle runtime. Returns at once; then call hf_runtime_connect (the machine needs a minute or two).
Billing runs per minute until hf_runtime_stop, the flavor: machine type from hf_hardware, e.g. "t4-small", "a10g-small", "l4x1". timeout: hard time limit such as "2h" or "8h". idle_minutes: shut down after this long with no activity and no run in progress (0 disables the idle shutdown). image: Docker image with Python 3; defaults to an official PyTorch + CUDA image. |
| hf_runtime_connectA | Attach to the Hugging Face runtime started with hf_runtime_start. Safe to call repeatedly and in every new session: it reports progress while the machine is still starting, and re-attaches to the same kernel once it is up. |
| hf_runtime_stopA | Shut down the Hugging Face runtime and stop its billing. Everything on its disk is lost: push results first (hf_push_run / save_checkpoint). |
| hf_whoamiA | Check the Hugging Face login: who the token belongs to and what it may do. |
| hf_searchA | Search the Hugging Face Hub for models or datasets, most downloaded first. kind: "model" or "dataset". |
| hf_uploadB | Upload a local file or folder to a Hub repo (created if missing, private by default). repo_id: "/". repo_type: "model", "dataset" or "space". |
| hf_downloadB | Download one file (or, with no filename, a whole repo) from the Hub to the local machine. |
| hf_push_runA | Upload a run's folder (checkpoints, metrics, log, script) from the runtime to the Hub. The upload goes straight from the remote machine, in the background, so large checkpoints never pass through this computer. Call it again to check progress. It uses this computer's Hugging Face login for that one upload; the token is not kept on the runtime. repo_id: defaults to "/<run_name>". |
| hf_space_statusA | Show a Space's state, hardware and URL. space_id is "/". |
| hf_space_hardwareB | Change a Space's hardware (e.g. "t4-small", "a10g-small", or "cpu-basic" for free). Paid hardware is billed per minute while the Space runs. sleep_minutes > 0 puts the Space to sleep after that long without visitors, which pauses the billing. |
| hf_space_pauseB | Pause a Space: it stops running and stops billing until restarted. |
| hf_space_restartB | Restart (or wake) a Space. On paid hardware, billing resumes. |
| setup_guideA | How to connect a place to run on: "colab", "kaggle", "huggingface" or "space". With no platform it reports what is already set up and what is missing. Use this whenever the user asks how to connect, or a tool says nothing is connected. |
| example_scriptA | Return a ready-made training script to pass to launch_training / hf_job_launch. With no name it lists the examples (LLM LoRA fine-tune, RL PPO, CV CNN). Each script's header says how to launch it and which settings it accepts. |
| kaggle_runtime_startA | Start a Kaggle GPU session without the browser, using the user's Kaggle login. Returns at once; then call connect_runtime (Kaggle needs a minute or two). After
that every runtime tool works on the Kaggle machine. It uses the account's free
weekly GPU hours until runtime_stop, competition: a competition slug to attach; its data appears under /kaggle/input/. (The user must have accepted the competition rules on kaggle.com.) datasets: comma-separated "owner/dataset" names to attach under /kaggle/input/. gpu: False starts a CPU session, which does not use GPU quota. |
| colab_runtime_startA | Prepare a Google Colab session. Returns one line for the user to run in Colab. Google does not let a program start a Colab session, so the user does two things: open a notebook and run the line. Nothing is copied back: when the line is running, call connect_runtime and the session is found automatically. Show the user the steps exactly as returned. |
| runtime_stopA | End the Colab/Kaggle session started with colab_runtime_start / kaggle_runtime_start. Download or push results first (save_checkpoint / hf_push_run). On Kaggle this stops the GPU-hours clock, and the files in /kaggle/working stay on Kaggle as the notebook's output. (A Hugging Face machine is stopped with hf_runtime_stop.) |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 54 tools
Several tool families overlap in purpose: launch_training vs hf_job_launch, connect_runtime vs hf_runtime_connect vs hf_runtime_start, and upload_file/download_file vs hf_upload/hf_download/hf_push_run all target similar actions across different backends. The long descriptions do clarify the distinctions (connected runtime vs rented HF job, local vs Hub vs runtime paths), which keeps it usable, but an agent must read carefully to choose correctly.
All names are snake_case, which is good, but the convention is mixed: some tools are domain-prefixed (hf_, kaggle_, colab_, cv_, rl_, notebook_) while others are bare verbs (run_code, launch_training, stop_run, fetch_image). The prefix scheme is readable and mostly predictable, but verbs are inconsistent (launch vs start vs connect, run vs execute).
54 tools is far above the 3-15 sweet spot and well past the 25+ 'heavy' threshold. While the server genuinely spans Colab, Kaggle, HF jobs, HF Spaces, notebooks, RL and CV helpers, several tools could be consolidated (e.g. separate start/connect/stop per backend, separate get_logs/get_metrics/get_run_status), making the surface feel sprawling.
Coverage is strong across the whole lifecycle: runtime start/connect/stop, code execution, file transfer, notebook editing, training launch/poll/stop, checkpoints, metrics plotting, Kaggle competition submission, HF Hub upload/download, and Space management. Minor gaps exist (no remote directory listing, no repo delete, no HF job log helper distinct from run logs), but agents can work around them.