Workloadtruth

What workloadtruth does

The workloadtruth MCP server lets an MCP-compatible agent inspect GPU telemetry and classify a workload as TRAINING, INFERENCE, or IDLE. Classification is based on observed behavior rather than labels supplied when a job is submitted, so it can be used to check whether a declared workload matches its telemetry.

The project also provides a command-line interface and exposes selected operations as MCP tools. The available agent operations are workload classification, benchmark execution, and audit-log verification. A continuous watch mode can append classifications to a local hash-chained log for later verification.

Classification is currently rule-based. The rules inspect four derived signal groups: average and variance of GPU utilization, memory-growth slope, and average and variance of power draw. Thresholds are documented in the source rather than hidden inside an opaque model.

How it works

The workloadtruth MCP server runs over stdio and uses the backend selected when the MCP command starts. The synthetic backend supports testing without an NVIDIA GPU and can generate documented training, inference, and idle traces. The nvml backend reads telemetry from NVIDIA hardware and requires an NVIDIA driver on the host.

A one-shot classification collects a telemetry window and returns the workload type, confidence, GPU index, sample information, and explanatory reasons. The CLI and MCP-facing operations support machine-readable JSON output where applicable, which is useful when results are consumed by scripts or agents.

The repository includes a benchmark for clean and deliberately altered synthetic traces. Its published results show that the current rules can be fooled by evasive training traces: training accuracy falls to 0% under the documented evasion transform, while evasive inference and idle traces remain accurate in that benchmark. These results describe synthetic tests, not live NVIDIA hardware.

Setup and configuration

Install the base Python package for synthetic operation:

pip install workloadtruth-cli

For NVIDIA telemetry, install the NVML extra:

pip install "workloadtruth-cli[nvml]"

To start the MCP interface, install the MCP extra on Python 3.10 or newer:

pip install "workloadtruth-cli[mcp]"

The MCP server is started with the workloadtruth mcp command and is configured as a stdio server in an MCP client. The README specifically identifies Claude and Cursor as supported client examples. The npm package is only a launcher; it expects the Python package and the workloadtruth executable to already be installed.

Tools and capabilities

The workloadtruth MCP server exposes these agent-callable tools:

• classify_workload: Classifies telemetry as training, inference, or idle.
• run_benchmark: Runs the synthetic evasion-robustness benchmark.
• verify_audit_log: Recomputes the hashes in a local audit log and checks whether its chain was altered.

The underlying CLI also includes watch, which continuously classifies windows and appends hash-chained entries, plus verify-log for checking those entries. classify accepts synthetic or NVML backends; synthetic profiles can be selected for test traces. Commands support JSON output for automation.

Limitations and notes

The experimental ML classifier flag is not available for producing results. The project currently ships only the inspectable rule-based implementation because the referenced research model and dataset were not published and the project lacks a real NVIDIA GPU in its build environment for collecting training data.

Do not treat the workloadtruth MCP server as a regulatory, compliance, or audit-certification tool. Its benchmark is based on synthetic telemetry, and its current rules are not robust against the documented evasive training transformation. NVIDIA hardware telemetry also depends on an available NVIDIA driver. The tool reports observed signals and classifications; it does not change the monitored workload.