vllm-ops-mcp — read-only ops truth for a local LLM server
Python 95 passing tests read-only secret redaction public repoThe problem
"Is the model server healthy?" is a deceptively hard question. A naive check confirms a port is listening — but a WSL2-mirrored-networking-relayed port can be invisible to a listener probe run from the Windows host, so a genuinely healthy server looks dead. And "a model is loaded" is not the same as "it actually generates." A health tool that answers the easy version of the question gives you false confidence exactly when you need the truth.
What I built
vllm-ops-mcp is a read-only ops/health MCP server for a local, WSL2/systemd-managed vLLM instance. Six tools, all read-only, each with an explicit "what it can't do":
- Two health tiers, both over real HTTP — every signal comes from an actual request to the OpenAI-compatible API, never a socket check.
check_health(deep=False)is liveness;deep=Truefires one minimal real completion to confirm the server generates, not just reports a model loaded. - Live serve-flag introspection —
get_serve_configprefers the live process's actual argv (/proc/<pid>/cmdlineof the systemd unit's MainPID) — ground truth of what's running now — falling back to the exec script only when the process is down. It live-recovered flags that weren't even in the repo's own grounding spec. - Secret redaction, defense-in-depth — any argv value whose flag name matches a sensitive pattern (
token/key/secret/password/credential) is redacted to[REDACTED]before return, across all three config sources. The flag name stays visible so the shape is still diagnosable. - Shared-infra protection — the two tools that fire a real inference call are rate-limited (default 20/min) precisely because this vLLM instance is shared infra other bots depend on; one caller hammering it can't starve the others.
Evidence you can check yourself
Public on purpose — every claim maps to a file you can open before you reply:
- Repo: github.com/jaimenbell/vllm-ops-mcp (MIT)
- Tests:
.venv/Scripts/python.exe -m pytest -q→95 passed, 7 skipped(the 7 skips are real-infra live smokes, gated behindVLLM_OPS_MCP_LIVE=1; they pass against the actual runningqwen3-14binstance). - An honest-capabilities table in the README maps every claim to its implementation function and the exact test — unit and live — that verifies it.
The README leads with the limitations, not the features. Per-process VRAM attribution
does not work on this operator's actual WSL2 GPU-passthrough setup — the live smoke
returns an empty processes list even while the vLLM process holds 13.7GB — so the
tool reports the empty result honestly rather than fabricating attribution. There is no
lifecycle control in this release: no start/stop/restart, and no env var that turns one
on. A restart tool needs its own gating design before it ships onto a read-only MVP — that's a
deliberate scope line, not an oversight.
What it shows about how I work
The differentiator here isn't a feature — it's a discipline: probe the thing you actually depend on (real HTTP, real generation, the live process's real argv), never a proxy for it. That, plus a README that tells you where the tool is blind before you rely on it, is how I build ops tooling you can trust in the exact moment something's on fire.