A local stdio MCP server that exposes a KVM device to MCP-capable agents (Claude Desktop, Claude Code, other agent hosts). It ships in the wheel — pip install --pre kvm-pilot installs it and the kvm-pilot-mcp launcher, pulling the mcp SDK (mcp>=1.17,<3) as a base dependency — either SDK major works, 1.x or 2.x (#241). The client/driver code stays stdlib-only; mcp is imported only in this subpackage, through one shim (_sdk.py) that resolves whichever major is installed.

⚠️ Beta. The core read paths are live-verified on real hardware (GL-RM1PE, beta maturity in the support matrix), but many device+capability combos are still tested against mocks and emulators only (see the Hardware-Compatibility list for what actually has; issue #7). Treat every result as unverified, and strongly consider running with dry-run enabled (below).

One name per concept, used consistently across the docs, the skill, and the code (#229):

• effect gate — the ALLOW_* operator opt-in that enables an effect on this server (opened out-of-band, in the server's own environment; never from within an agent session).
• effect class — the EffectClass taxonomy that classifies what an operation does (a Ctrl+Alt+Del chord is a power effect, not HID), and so which effect gate it needs.
• act tools — all gated state-changers, reversible or not (HID, media, power, boot config, SSH exec, appliance reset, external write).
• destructive — the subset of act tools annotated destructiveHint=true (irreversible); the reversible media/calibration/external-write tools are act tools but not destructive.
• playbook — the operating guidance bundled with the skill (skill/references/*.md), re-served at runtime by the doctrine tool; topic is only the doctrine parameter naming one.

Every tool declares all four MCP hints explicitly (a CI test enforces it — the spec defaults are punitive: an unset destructiveHint reads as true and an unset openWorldHint reads as "reaches the internet"). Clients build real policy from these bits (auto-approval and parallel dispatch of read-only tools, confirmation UI on destructive ones), so precision matters. Hints are advisory, never a security boundary — the ALLOW_* effect gates and per-invocation approvals below apply regardless of annotation.

Every tool result names the host and driver it acted on, and read-only tools always run with a deny-all confirm callback, so a bug in a read path can never trip a destructive operation. Drivers are built per call and closed afterwards — important for Redfish BMCs, which cap concurrent sessions device-side (a leaked session can lock operators out of the BMC).

Every act tool — the gated state-changers, from HID (type_text, press_key, send_shortcut, ctrl_alt_delete, mouse, calibrate_mouse) through media (mount_iso, eject), power (power, wake), config (set_boot_device, amt_enable), in-band exec (ssh_exec), and the appliance (appliance_reboot) to the external write (file_firmware_report) — requires two things, not one (#234 unified the last five onto this pipeline: same receipts, same audit terminals, same typed same-path denials):

1. Allowed — the operator opened the tool's effect gate in the server's own environment, and the target profile is on KVM_PILOT_MCP_PROFILES (if set). Tools are classified by effect class, not transport: ctrl_alt_delete and a Ctrl+Alt+Del / Magic-SysRq chord are reboots, so they need KVM_PILOT_MCP_ALLOW_POWER — an agent can't reboot the box through the weaker HID gate by picking a different actuator.
2. Approved at run time — a per-invocation human approval via MCP elicitation when the client supports it (interactive posture); otherwise an explicit confirm=true under the operator's standing policy (pre-authorized posture — what an unattended install loop uses, since no human is present to answer).

Denials (gate closed, declined/cancelled, not confirmed, invalidated mid-approval) come back as a normal result with approved: false, a typed outcome (cancelled is a benign client-side interruption; denied is an explicit no — branch on outcome, not on the human-facing strings, #149) and a reason — the agent can re-plan, never left hanging.

Approval receipts (#72): an approval is a signed, expiring, single-use receipt bound to the exact invocation (host, tool, effect, args-hash, dry-run, approver). It is re-verified immediately before dispatch and consumed on use: any bound field changing after approval, an expired receipt (KVM_PILOT_MCP_RECEIPT_TTL, default 60 s), or a replay of a consumed receipt fails closed as a denial-shaped result. Approved results carry receipt: {id, state} and a real approval.expires. Every destructive invocation terminal — approved, denied, consumed, expired, mismatched, replayed, dispatch-exception — emits one JSON audit record on the kvm_pilot.mcp.audit logger (capture the server's stderr/logging to retain the trail; receipts are per-process, a server restart voids them).

Standing approvals (#192, opt-in). When per-invocation prompts are too noisy for an interactive flow (arrow-keying an installer re-prompts per keystroke), the operator can set KVM_PILOT_MCP_STANDING_TTL=<minutes> (0/unset = off). The elicitation form then offers standing_minutes: approve once for a (host, effect class) scope and that many minutes; invocations in scope consume the grant instead of re-prompting. It is not the ELICIT=off sledgehammer — a human still signs off, just once per window, and only if they choose (standing_minutes=0 stays one-shot). A grant is not bound to args (that is the point) but is signed with the per-process key, capped at 8 h, and revoked the instant the operator flips the effect gate or dry-run — the same _bound_state re-check that guards a pending approval. Each consumption still mints its own single-use receipt and audits with the grant id (via: standing); opening a window emits a standing-granted record. Live grants show in the session tool's standing_approvals (scope + time left). Never spans a restart.

Symptom: act tools return approved: false, approver: null, and denied_reason: "approval cancel" (or "denied by approver"), while read-only tools keep working. Cause: the chat client cancelled the pending approval prompt — sending a new message kills the in-flight elicitation; the action never reached the target, and the result's remediation field says so. Fix: answer the prompt before typing the next message; if a client keeps killing approvals, the operator may set KVM_PILOT_MCP_ELICIT=off (trade-off: no per-call human approval — the remedy advertises this escape hatch only after ≥2 consecutive client-side kills). Full narrative: Troubleshooting & FAQ. The duration-scoped standing approval that removes the per-keystroke re-prompt without giving up human sign-off shipped as KVM_PILOT_MCP_STANDING_TTL (#192) — see Standing approvals above.

A tool the active driver cannot serve returns a clean MCP tool error naming the driver kind and the missing capability (it never AttributeErrors). support_matrix takes no profile and contacts no device — it works identically for every driver.

The MCP surface is deliberately small. For anything outside the table, pick the right interface (the skill's Choosing an interface matrix is the full guide):

• firmware-update → the CLI (kvm-pilot firmware-update); no MCP tool. (Bounded events and the read-only firmware_check currency readout ARE tools since #233; only follow-mode streaming stays CLI.)
• MSD mode switching → the Python library.
• Serial console (SOL) on AMT/IPMI → the CLI (kvm-pilot console); no MCP serial tool — an interactive byte stream doesn't fit the synchronous stdio transport, and won't (documented boundary, not a gap). AMT/IPMI feature enablement other than the redirection listeners (amt_enable) — e.g. re-provisioning — stays out of band.
• Disabling AMT KVM user-consent → possible via amt_enable(consent_off=true) but only behind the dedicated KVM_PILOT_MCP_ALLOW_CONSENT_OFF gate; the operator-present CLI path is kvm-pilot amt enable-kvm --no-consent.
• Restart kvmd / inspect /etc/kvmd on the appliance → out-of-band SSH to the appliance. (A full appliance reboot does have a tool now — appliance_reboot, ALLOW_APPLIANCE-gated; power still acts on the managed host, never the appliance.)
• View the screen when snapshot fails (503, or a tiny frame while a signal is present — typically H.264 at the panel's native resolution) → the WebRTC/Janus stream or the vendor web UI.

Preflight first. On connecting to any device, call healthcheck before you trust it for real work (issue #80) — it surfaces readiness/recovery, security, and firmware risks up front (most importantly, whether there is any out-of-band recovery path if the guest hangs). A CRITICAL finding should gate the destructive power tool below. Note: the server does not yet auto-run this on connect, so the agent must call it as the first step.

The power gate is layered; no single layer is trusted on its own:

1. Operator opt-in (the real gate). The power tool is disabled by default. It only works when the human operator sets KVM_PILOT_MCP_ALLOW_POWER=1 in the server's own environment (e.g. the env block of the MCP host config) before starting the server. The tool's refusal message deliberately does not spell out the variable assignment — an agent must not be able to relay the incantation; a human has to read this README and decide.

2. confirm=true second factor. Even with the gate open, power requires an explicit confirm=true argument. This flag is model-supplied — it is not human approval and must not be treated as such.

3. Client-side human approval. MCP hosts should require per-call human approval for power (in Claude Desktop / Claude Code, do not put this tool on an "always allow" list). The destructiveHint/readOnlyHint annotations are published so hosts can render a differentiated approval UI — but annotations are hints, never a security boundary.

4. Read-only launch mode (#196). With KVM_PILOT_MCP_READ_ONLY=1 the state-changing tools are not registered at all (tools/list shows only the read-only surface, minus ssh_discover — an active scan has no place in a least-privilege posture), and two independent layers back the filter up: every effect gate is force-closed regardless of ALLOW_*, and every driver is built with a deny-all confirm — so even a bypassed registration cannot mutate a target (tool filtering alone is not enforcement; that lesson is CVE-2026-46519). Results carry read_only: true. The trust ladder for a new fleet: start READ_ONLY (intake, status reports, support evidence) → graduate to DRY_RUN (rehearse destructive flows, calls logged not sent) → open ALLOW_* effect gates one at a time as the matrix verifies your hardware.

   

5. Dry-run. With KVM_PILOT_MCP_DRY_RUN=1 every driver is built with dry_run=True: destructive commands are logged and skipped, and every tool result says it ran in dry-run mode. Recommended default until your own device+capability combos are verified in the matrix.

6. Untrusted screen content. snapshot and classify_screen feed target-controlled console output into the agent's context. A compromised or hostile host can render text designed to steer the agent (prompt injection) — one more reason to keep layer 3 on.

Every tool accepts an optional profile argument, and a model-supplied value takes precedence over the KVM_PILOT_PROFILE pin. ~/.config/kvm-pilot/config.toml therefore acts as a credential store the agent can roam: any profile the file defines can be targeted by the agent, not just the pinned one. Keep only hosts you are willing to expose in the config file this server can read (or point KVM_PILOT_CONFIG at a dedicated file). Pinning via KVM_PILOT_HOST/KVM_PILOT_USER/KVM_PILOT_PASSWD env vars instead is immune to retargeting — env values beat file-profile values. Result provenance (host / driver in every result) makes the acted-on target visible in transcripts.

pip install --pre kvm-pilot     # installs the CLI, the MCP server, and the `mcp` SDK
kvm-pilot-mcp                    # start the stdio server (or: python -m kvm_pilot.mcp.server)

Add to your MCP config (claude_desktop_config.json). Dry-run is enabled here on purpose — remove it only once your hardware is verified in the matrix (or you accept the risk), and add KVM_PILOT_MCP_ALLOW_POWER only if you want the power tool live:

{
  "mcpServers": {
    "kvm-pilot": {
      "command": "kvm-pilot-mcp",
      "env": {
        "KVM_PILOT_PROFILE": "homelab",
        "KVM_PILOT_MCP_DRY_RUN": "1",
        "ANTHROPIC_API_KEY": "sk-..."
      }
    }
  }
}

Keep per-call approval enabled for power in the host UI.

A single-file .mcpb bundle (zero-toolchain install) is tracked in issue #7.