Denpex MCP server

Diagnose GPU/ML training failures — CUDA OOM, NCCL timeouts, Xid faults, NaN loss, checkpoint corruption — without leaving your AI tool. Ask Claude Desktop, Cursor, or Claude Code to "diagnose the crash in ./logs/train.err" and Denpex reads the log straight off disk and hands back the root cause and the fix.

• 🩺 Root cause + escalating fix (primary → fallback → emergency), verification command, and prevention.
• 🧭 Find the culprit rank in a distributed/NCCL hang, and route GPU Xid faults to the right node action — offline, instantly.
• 📚 312-class failure encyclopedia searchable by error code or symptom.
• 🔒 Zero-egress mode (DENPEX_LOCAL=1): diagnose entirely on-host, nothing leaves the machine. Plus client-side PII scrubbing even in cloud mode.

Quick start (60 seconds)

1. Get an API key (optional but recommended)

Sign in at denpex.com/dashboard → API Keys and create a key (dpx_…). The key unlocks the cloud LLM fallback on novel errors, your diagnosis history, quota, and fleet incidents. Without a key, diagnose_crash, lookup_failure, and analyze_cascade still work fully offline.

2. Add it to your client

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "denpex": {
      "command": "npx",
      "args": ["-y", "denpex-mcp"],
      "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
    }
  }
}

Restart Claude Desktop.

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "denpex": {
      "command": "npx",
      "args": ["-y", "denpex-mcp"],
      "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
    }
  }
}

claude mcp add denpex -e DENPEX_API_KEY=dpx_your_key_here -- npx -y denpex-mcp

3. Use it

"My training job crashed — diagnose the log at ./logs/rank0.err." "What does Xid 79 mean?" "This 64-GPU run is hung. Which rank failed first?" (→ analyze_cascade)

Or pick the diagnose-training-crash prompt your client surfaces.

Offline / air-gapped mode

Diagnose entirely on-host — no network, no logs leaving the cluster. Ideal for VPCs, secure data centers, and privacy-sensitive labs. Add DENPEX_LOCAL=1:

{ "mcpServers": { "denpex": {
  "command": "npx", "args": ["-y", "denpex-mcp"],
  "env": { "DENPEX_LOCAL": "1" }
} } }

The bundled engine (31 fast patterns + the 312-class encyclopedia + Xid routing + cascade localization) covers the overwhelming majority of real failures. The LLM fallback for novel errors is cloud-only and simply unavailable offline.

Tools

| Tool | What it does | Needs | |------|--------------|-------| | diagnose_crash | Root cause + escalating fix from logs / file / dir. | works offline | | lookup_failure | Search the 312-class encyclopedia by code/keyword/symptom. | works offline | | analyze_cascade | Find the culprit rank in a distributed hang; route Xid faults. | works offline | | check_quota | Your plan and remaining diagnoses this month. | API key | | recent_diagnoses | Recall your recent diagnoses and their fixes. | API key | | ask_followup | Conversational follow-up on a diagnosis. | Team plan / trial | | check_versions | Flag known-bad CUDA/PyTorch/NCCL/driver combos. | Team plan / trial | | list_incidents | Incidents Denpex's monitor caught & escalated on your fleet. | Scale plan |

Gated tools degrade gracefully — they tell you exactly which plan unlocks them and which tools work on your current plan. The failure encyclopedia is also exposed as resources at denpex://failures/{slug}.

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | DENPEX_API_KEY | — | Your dpx_… key. Enables cloud tools. | | DENPEX_API_URL | https://api.denpex.com | Override the API base (self-host / staging). | | DENPEX_LOCAL | 0 | 1 → diagnose entirely on-host (zero egress). | | DENPEX_PRIVACY | off | mask / strict → scrub PII from logs before they leave the machine. |

Develop

npm install
npm run build      # regenerates the offline corpus, then bundles dist/index.js
npm test           # 48 unit + protocol-integration tests
npm run inspector  # interactive protocol inspector (MCP Inspector)

The offline corpus (src/data/denpex_patterns.json) is generated from the repo's single source of truth via npm run bundle:patterns — never hand-edit it.