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

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.