Skip to main content
CruciHiL ships a FastMCP server that exposes 14 tools to any MCP-compatible AI client. With the MCP server connected, an AI assistant can query rigs, trigger test runs, analyze failures, and generate new test suites — all from a conversation.

​
Starting the MCP server

CRUCIHIL_BASE_URL=https://your-server.example.com \
CRUCIHIL_API_KEY=your-api-key \
python -m crucihil.mcp.server
For SSE transport (HTTP, suitable for remote connections): 
CRUCIHIL_BASE_URL=https://your-server.example.com \
CRUCIHIL_API_KEY=your-api-key \
CRUCIHIL_MCP_TRANSPORT=sse \
python -m crucihil.mcp.server
The SSE server binds to 0.0.0.0:8001.

​
Environment variables

VariableRequiredDescription
CRUCIHIL_BASE_URLYesHTTP(S) base URL of the CruciHiL control plane
CRUCIHIL_API_KEYYes (unless OAuth)API key for global client access
CRUCIHIL_MCP_TRANSPORTNostdio (default) or sse
SECRET_KEYOAuth onlyHS256 shared secret for JWT verification
MCP_SERVER_URLOAuth onlyPublic URL of the MCP server

​
Connecting Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS): 
{
  "mcpServers": {
    "crucihil": {
      "command": "python",
      "args": ["-m", "crucihil.mcp.server"],
      "env": {
        "CRUCIHIL_BASE_URL": "https://your-server.example.com",
        "CRUCIHIL_API_KEY": "your-api-key"
      }
    }
  }
}
Restart Claude Desktop. You should see CruciHiL tools appear in the tools panel.

​
Connecting Cursor

In Cursor settings, add an MCP server: 
{
  "mcp": {
    "servers": {
      "crucihil": {
        "url": "http://localhost:8001/sse",
        "env": {
          "CRUCIHIL_API_KEY": "your-api-key"
        }
      }
    }
  }
}
Start the SSE server first: 
CRUCIHIL_MCP_TRANSPORT=sse \
CRUCIHIL_BASE_URL=https://your-server.example.com \
CRUCIHIL_API_KEY=your-api-key \
python -m crucihil.mcp.server

​
Connecting GitHub Copilot

Use the SSE transport. Add the server URL to your Copilot MCP configuration in VS Code settings.

​
Available tools (14 total)

​
Rig management

ToolDescription
list_rigsList all registered rigs with connection status
get_rig_configGet hardware summary and connectivity for one rig
register_rigRegister a new rig, returns a one-time API key

​
Test runs

ToolDescription
list_runsList recent runs, optionally filtered by rig
get_run_summaryFull summary of one run — pass rate, duration, counts
run_test_suiteCreate a queued run and push it to the connected agent
cancel_runCancel a running suite

​
Result inspection

ToolDescription
get_resultsList test results for a run with optional status filter
get_signal_traceExtract signal samples for one signal across a run
describe_failureAll failure context in one call — errors, logs, signal traces

​
Signal and suite introspection

ToolDescription
list_signalsParse a DBC file and return all signal metadata
list_testsParse a YAML manifest and return all test metadata

​
AI-assisted

ToolDescription
generate_test_suiteScaffold YAML + Python from natural language, with DBC/TOML context
analyze_componentExtract signal interface of a C/C++ SWC (requires [analyze] extra)

​
Typical AI workflows

​
Failure analysis

User: Why did test brake_response fail in the last run on rig bench_01?

Claude:
  → list_runs(rig_name="bench_01", limit=1)
  → describe_failure(run_id="...", test_id="brake_response")

Claude: BrakeStatus.Pressure was 0.0 at t=1.203s — the signal never arrived.
        EngineData.RPM was at 500ms cadence instead of 10ms. Bus load was 94%.
        The BrakeDemand frame likely missed its arbitration window.

​
Onboarding a new rig

User: Register a new rig called bench_02 and tell me how to connect it.

Claude:
  → register_rig(rig_name="bench_02")

Claude: Registered. API key: chk_xxxxxxxx (save this — shown once).
        On the bench machine:
          export CRUCIHIL_API_KEY=chk_xxxxxxxx
          export CRUCIHIL_BASE_URL=https://your-server.example.com
          crucihil discover --describe "your hardware"
          crucihil agent --rig rigs/bench_02.toml

​
Generating a test suite

User: Generate a test suite for the engine management SWC. Use the DBC
      at defs/powertrain.dbc and target the bench_01 rig.

Claude:
  → generate_test_suite(suite_name="engine_management_validation", ...)

Claude: Created tests/suites/engine_management_validation.yaml and
        tests/suites/engine_management_validation.py with 5 test functions.
        Run with:
          crucihil run --suite tests/suites/engine_management_validation.yaml \
                       --rig rigs/virtual.toml

​
See also