mcp-health-probe

# MCP Health Probe ## What It Does Defines the canonical health classification used by `/<plugin>:status` commands so the user can distinguish "the MCP server didn't start" from "the MCP started but the upstream API is failing." Three core states (OFFLINE / DEGRADED / HEALTHY) cover the universal case; a fourth label, `PRESENT (untested)`, is a refinement of HEALTHY for MCPs that defer credential validation to first tool invocation. Extracted from yellow-morph's `/morph:status` and generalized for any plugin with an MCP + upstream HTTP API. ## When to Use Load when authoring a `/<plugin>:status` command for a plugin whose MCP server depends on an upstream HTTP API (Morph, Semgrep, Perplexity, etc.). The skill defines the state machine, the classification table, and the canonical reference implementation so each status command behaves consistently. ## Usage Health classification pattern for `/<plugin>:status` commands that expose an MCP server. Three core states, plus one refinement label for MCPs that do not validate credentials at startup. The subsections below cover the states, the detection pattern, the classification table, the rationale, a reference implementation, and the anti-patterns to avoid. ### States - **OFFLINE** — The MCP server did not start or crashed. None of its tools are visible to the agent via `ToolSearch`. No API probe is run in this state (there is no point — the server isn't there). - **DEGRADED** — The MCP tools are visible (server started), but the upstream HTTP API returns a non-200 response to a minimal health probe. Tools are callable but will fail at invocation time until the upstream recovers or the credential is fixed. - **HEALTHY** — MCP tools are visible AND the API probe returned 200 (or was skipped because the credential isn't readable from the shell, AND the MCP validates credentials at startup so visibility implies a working credential — see "Skipped probe" below). - **PRESENT (untested)** — Refinement of the skipped-probe HEALTHY case for MCPs that do NOT validate credentials at startup (exa, tavily): the credential is stored and the MCP loaded, but neither the API probe nor MCP startup has validated it. Use this label only in the per-skipped-probe row of the table; aggregate state for the user-facing banner remains HEALTHY (the MCP is usable; first invocation will surface any auth problem). ### Pattern ```text Step 1: Tool visibility check (authoritative OFFLINE detection) Call ToolSearch with query "+<plugin> <distinctive-tool-name>". If the expected MCP tool is not returned: state = OFFLINE. Skip to Step 4. Step 2: Credential source probe (non-authoritative) Report whether the credential is set via shell env vs userConfig vs neither. Useful UX but not part of the HEALTHY/DEGRADED decision — MCP visibility in Step 1 is the authoritative signal that a credential is configured and accepted. Step 3: Upstream API probe (HEALTHY / DEGRADED) If the credential is readable from the shell (shell env var path): curl -s -o /dev/null -w '%{http_code}' \ --connect-timeout 5 --max-time 8 \ -H "Authorization: Bearer ${<PLUGIN>_TOKEN}" \ <minimal health endpoint> 200 → HEALTHY 401/403 → DEGRADED (credential invalid or revoked) 429 → DEGRADED (rate limit) other non-200 / curl exit != 0 → DEGRADED (network or upstream fault) If the credential lives only in userConfig and is not readable from the shell: skip the API probe. The MCP server authenticated at startup; if the credential were bad the tools would be absent (OFFLINE). Treat "skipped" as HEALTHY for classification purposes. Step 4: Report with next steps Print a short state banner plus a "What to do" block tailored to the state. Examples: OFFLINE: point at /<plugin>:setup; suggest disable+enable plugin cycle to fire the userConfig prompt; reference known Claude Code quirks (issue #39827). DEGRADED: 401 → re-enter token; 429 → wait / upgrade plan; other → check upstream status page. HEALTHY: nothing to do. Optionally surface rate-limit / credit remaining if the upstream exposes it. ``` ### Classification table | MCP tools | API probe | Startup validates credential? | State | | --------- | ------------------------ | ----------------------------- | ------------------ | | not loaded| (not run) | n/a | OFFLINE | | loaded | 200 | n/a | HEALTHY | | loaded | skipped (userConfig-only)| yes (e.g., perplexity) | HEALTHY | | loaded | skipped (userConfig-only)| no (e.g., exa, tavily) | PRESENT (untested) | | loaded | 401 / 403 / 429 / error | n/a | DEGRADED | The "Startup validates credential?" column captures whether the MCP server hard-fails at startup when the credential is missing or invalid (so tool visibility is itself a credential-validation signal). MCPs that defer validation to first tool invocation (exa @ 3.1.8, tavily @ 0.2.17 at the time of writing) should report `PRESENT (untested)` rather than HEALTHY when the API probe is skipped — the credential is stored but unverified. ### Why this shape - **ToolSearch is the authoritative liveness signal.** Checking for a shell env var or grepping `~/.claude/settings.json` for a userConfig key both report "config is present" but not "MCP actually started." Only `ToolSearch` sees whether tools are registered with the current session. - **Separate "reachable" from "authenticated."** Upstream API probes conflate the two — a 401 means reachable but bad credential. Keeping the states distinct tells the user whether to check their network or their token. - **Skip-probe is HEALTHY, not DEGRADED — but only when MCP startup validates the credential.** This rule applies to MCP servers that reject a missing or invalid credential at startup, so tool visibility implies a valid credential (e.g., perplexity hard-fails at startup). For MCP servers that start without credential validation and only fail at tool invocation (e.g., exa, tavily), tool visibility does NOT imply authentication; treat skip-probe as `PRESENT (untested)` rather than HEALTHY. Document the per-MCP behavior inline in the status command. ### Reference implementation `plugins/yellow-morph/commands/morph/status.md` is the canonical implementation. Other `:status` commands adopting this pattern should match its structure (steps, states, reporting format) so users see a consistent surface across plugins. ### Anti-patterns - **Do not** treat "shell env var set" as HEALTHY without checking MCP tool visibility. The MCP may have crashed at startup despite the env var being present. - **Do not** run the API probe before the tool-visibility check. If the server is OFFLINE, the probe wastes network time and may burn a rate- limited API call. - **Do not** omit the "What to do" block — a state without an action is a dead-end for the user. Every state should have at least one concrete next step. - **Do not** invent ad-hoc states like "INITIALIZING" or "UNKNOWN". The surface is deliberately small: three core states (OFFLINE / DEGRADED / HEALTHY) plus the documented `PRESENT (untested)` refinement of HEALTHY for non-startup-validating MCPs. If a probe is ambiguous beyond those cases, report DEGRADED with the ambiguity in the "What to do" block.