MCP Watchdog

Know which MCP servers are responding — independent of what the editor still shows.

The editor can still show tools after a server has gone quiet — after idle, sleep, or a network drop. MCP Watchdog is an independent check of the servers you approved. It shows status, latency, and failure details, then offers a next step.

Works in Cursor, Windsurf, VS Code, VSCodium, and other forks that install from Open VSX. Host roadmap (Claude Code–class CLI later, not JetBrains-first): docs/STRATEGY-THESIS.md — Where Watchdog exists.

Install (recommended for Cursor): MCP Watchdog on Open VSX — primary download channel for Cursor, Windsurf, VSCodium, and most VS Code forks.

Repository: github.com/vaibhav11123/mcp-watchdog

Install

Install in Cursor (recommended)

Most Cursor installs pull extensions from Open VSX, not the VS Marketplace:

1. Extensions (Cmd+Shift+X) → search MCP Watchdog
2. Or open MCP Watchdog on Open VSX → Download / install from the registry
3. Or CLI: cursor --install-extension mcp-watchdog.mcp-watchdog

All install channels

After install, reload the window. Open the activity bar MCP Watchdog icon (not the Extensions detail page).

Editor

Watchdog opens its own connection to each approved server. The status bar shows Watchdog: healthy/total. Overview and the Servers tree show latency and a short failure snippet.

That result is Watchdog’s probe. It does not read the editor’s MCP client, so a green Watchdog row does not mean the editor’s own session is healthy.

When a check fails, the next steps are separate:

• Accept — acknowledge the failure; status-bar chip drops that server from N/M (Overview still shows Failed + Accepted). Probing continues.
• Fix… — guided remediation by cause class (e.g. missing token vs 401 vs expired session vs spawn path); copy commands, open owning config, AWS login terminal, credential wizard, retry.
• Remove — delete the server key from the owning config file (or Disable Watchdog monitoring).
• Retry probe — run Watchdog’s check again.
• Restart editor MCP — only on the failure toast, and only when the host exposes workbench.mcp.*. Cursor and some forks do not.
• Reload Window — when the editor client stays stuck. Quit Cursor is the last resort.

Demo

Independent probe → cause sentence → Fix… → recovery. Prefer the Accept / Fix… / Remove story in docs/media/GIF-RECORDING.md when re-recording (no secret values in frames). The punchline worth sharing is Verified: after Fix — when the Overview shows the server came back.

Watchdog Cloud (preview — optional)

Cloud is not required for the editor product. The core customer path is still status bar + failure toast in Cursor/VS Code.

If you self-host later: remote health checks, schema change alerts, and configuration policy checks with an audit trail (policy runs outside the MCP tool-call path). Opt-in via mcpWatchdog.cloudBridge.enabled and cloudBridge.url (names-only incidents; fail-soft). Default is off. Self-host notes: packages/cloud/README.md.

Requirements

• VS Code or Cursor with a compatible engine: this manifest declares engines.vscode: ^1.105.0 (adjust if you need a different floor after testing).
• A workspace folder open in the editor.
• MCP config in at least one of:
  • .vscode/mcp.json — VS Code workspace (servers object)
  • .cursor/mcp.json — Cursor workspace (mcpServers or servers)
  • ~/.cursor/mcp.json — Cursor global
  • VS Code user mcp.json — e.g. ~/Library/Application Support/Code/User/mcp.json on macOS
  • Windsurf — ~/.codeium/windsurf/mcp_config.json
  • Claude Code — ~/.claude.json (mcpServers block)
  • Claude Desktop — claude_desktop_config.json (mcpServers; fully quit the app after edits so MCP reloads)
  • Layers merge (workspace project files override globals).
• In multi-root workspaces, workspace .vscode/mcp.json / .cursor/mcp.json are merged from every folder (later folder wins on the same server name). ${workspaceFolder} on global layers uses the first folder only; each workspace layer expands with that folder’s path.

Where is the UI?

VS Code has two different sidebars:

Other extensions that “show UI when opened” usually either (1) open their own activity bar panel (GitLens, Docker, etc.), (2) add a Getting Started walkthrough (first install), or (3) use a webview in the sidebar. MCP Watchdog uses (1) + a walkthrough on first install.

After install, run Help → Welcome → MCP Watchdog: Get started (walkthrough), or MCP Watchdog: Open Servers View.

Quick start

1. Add MCP config (see examples below). Command: MCP Watchdog: Open MCP Config.
2. Open that folder. Click the MCP Watchdog icon in the activity bar → Servers (not the Extensions panel). The status bar shows Watchdog: n/n when servers are monitored.
3. Optional: View → Output → MCP Watchdog for detailed logs.

Screenshots

Status bar — aggregate health (Watchdog: healthy / total) on the bottom right (distinct from the editor’s own MCP chip):

Servers view — per-server state and last ping latency in the MCP Watchdog activity bar sidebar:

Example mcp.json

{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "remote": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Security: only configure servers you trust. This extension runs command (e.g. npx, node) and opens HTTP(S) URLs you specify. It declares untrustedWorkspaces.supported: false, so it does not activate in VS Code Restricted Mode; open a trusted folder (and use Watchdog’s own approval gate) before monitoring.

Config strings expand ${workspaceFolder}, ${userHome}, and ${env:NAME} (see below). A third transport is SSE: type: "sse" (or url plus transport: "sse"); prefer Streamable HTTP when the server supports it.

Trust & consent

By default (mcpWatchdog.requireApproval: true), Watchdog does not spawn stdio processes or open HTTP connections until you approve. On first load (or after mcp.json changes), you get a notification with Review & Allow / Not now. Review & Allow opens a multi-select list of every server (name — command args or name — url); only the subset you confirm is monitored. Approval is stored per workspace folder and survives reloads. Changing a command, arg, or URL in config re-prompts. Not now leaves the status bar at $(shield) Watchdog: untrusted — click it to review again. Set requireApproval to false on a trusted single-user machine to auto-connect like 0.1.x.

Config lint

With mcpWatchdog.diagnostics.enabled (default true), Watchdog reports mcp.json structure issues in the Problems panel: invalid JSON, a missing servers / mcpServers root, and entries that have neither command nor url.

Variable expansion

In config strings (and nested arrays/objects), Watchdog expands:

• ${workspaceFolder} — that layer’s workspace folder (first folder for global layers)
• ${userHome} — the OS home directory
• ${env:NAME} — environment variable; if unset, the literal ${env:NAME} is left in place

${input:…} is not expanded (needs interactive UI). Env and header values are never logged or rendered in the UI.

Failure context and auth

Failed or degraded servers show a short recent-log snippet on the Servers tooltip, Overview, and status-bar tooltip. HTTP 401 / Unauthorized surfaces as Auth required (HTTP 401) and stays in failed or degraded — Watchdog does not add a separate auth state or complete OAuth for you.

Overview sparklines

The Overview webview draws a small latency sparkline from the last ~40 healthy ping samples per server, next to the server name.

Incident timeline

Watchdog keeps an in-memory ring of the last ~200 state transitions (not written to disk until you export). Use MCP Watchdog: Export Incident Timeline (Markdown) to save that buffer as a Markdown file.

Commands

• MCP Watchdog: Show Server Status — Quick pick with per-server state.
• MCP Watchdog: Accept Failure / Unaccept Failure — Drop or restore a failed server on the status-bar chip.
• MCP Watchdog: Fix Failure… — Guided remediation QuickPick.
• MCP Watchdog: Remove Server — Delete the key from the owning mcp.json (or Disable monitoring).
• MCP Watchdog: Review Trusted Servers — Change the approved subset or revoke trust.
• MCP Watchdog: Retry All Probes / Retry Probe…
• MCP Watchdog: Open Servers View — Focus the Servers tree.
• MCP Watchdog: Open MCP Config — Open or create .cursor/mcp.json / .vscode/mcp.json.
• MCP Watchdog: Export Incident Timeline (Markdown) — Save the in-memory incident ring (~200 transitions) as Markdown.

Settings (mcpWatchdog.*)

Opt-in advisories

These never force a server into failed on their own:

• checkEmptyTools — after a successful ping, call tools/list and show a tool count on Overview / tree.
• detectToolDrift — fingerprint sorted tool names; when the set changes, show an info toast via toolDriftNote (kept out of lastError so healthy servers do not look failed).
• passiveHttpProbe — for HTTP servers in interval mode, HEAD/GET the URL before a full MCP connect; if the endpoint answers but MCP fails, mark degraded with an advisory message.

Alerts

When a server fails, Watchdog shows Accept, Fix…, Remove, Retry probe, Restart editor MCP (when workbench.mcp.* is available), Show Log, Reload Window, Quit Cursor, and Mute 1h. Accept quiets the chip without marking the server healthy; Mute only silences toasts for 1h. Retry probe only restarts Watchdog’s check. Set mcpWatchdog.notify to all to also get recovery toasts. Repeated failures within 10 minutes collapse into a single flapping warning.

Auth probe (opt-in)

Per-server mcpWatchdog.perServer.<name>.authProbe can call one MCP tool after a successful ping to verify credentials. Default: unset (read-only). May have side effects or cost — enable only when you understand the tool.

Probe modes

Settings changes apply within ~1s without reloading the window; mcp.json edits reload monitors via the file watcher.

Privacy & data

• Product telemetry (PostHog) is on by default (mcpWatchdog.telemetry.enabled). Anonymous allowlisted events (activation, triage, commands) use a random install id — never env/header values, secrets, workspace paths, or raw error text. Setting is in Settings (search “telemetry”); also blocked when the editor’s telemetry setting is off. Dictionary: telemetry.json.
• Watchdog monitors servers from merged mcp.json layers. Cursor may list additional editor/plugin MCPs that are not in those files; the status-bar N/M is healthy/total of Watchdog’s set.
• Separate from telemetry: traffic to your configured MCP servers only (stdio / HTTP as in mcp.json).
• Opt-in Cloud bridge (cloudBridge.enabled, default off) posts names-only incidents to your self-hosted Cloud (fail-soft if unreachable).
• Do not commit secrets inside mcp.json in shared repos; use environment variables or secret stores appropriate to your team.

Known limitations

• Reads workspace .vscode/mcp.json / .cursor/mcp.json from all multi-root folders (later folders override same server names), plus globals ~/.cursor/mcp.json, VS Code user mcp.json, Windsurf mcp_config.json, Claude Code ~/.claude.json, and Claude Desktop claude_desktop_config.json. Global ${workspaceFolder} expands using the first folder only.
• Independent of the editor’s MCP UI: native MCP may show different state until the next Watchdog ping.
• HTTP transport may combine SDK-level reconnection with Watchdog-level retries. SSE is supported via SDK SSEClientTransport but is deprecated upstream — prefer Streamable HTTP when possible.
• Malformed mcp.json: invalid JSON shows an error notification; fix the file and save.
• Tool-drift fingerprints are name-only (no schema hash); passive HTTP is a light HEAD/GET, not a substitute for MCP health.

Troubleshooting

See Screenshots above for the Marketplace / README visuals.

Development

npm install
npm run compile
npm run build

• Run Extension / Run Extension (mcp-watchdog-test workspace) from .vscode/launch.json.
• Fixture: mcp-watchdog-test/ (optional; not shipped in VSIX).
• Headless smoke: npm run smoke.
• Start here (progress / routing): docs/STATUS.md — bird’s-eye phase, claim ladder, what to update next.
• Release train / soak: docs/RELEASE.md · Pre-ship testing: docs/TESTING.md.
• GTM role (Instinct): docs/GTM-ROLE.md · Guardrails: docs/GTM-GUARDRAILS.md · Comms: docs/GTM-COMMS.md · Publish checklist: docs/GTM-PUBLISH.md.
• Strategy thesis: docs/STRATEGY-THESIS.md — reliability + recovery intelligence; claim ladder; metric formulas.
• Target architecture: docs/TECHNICAL-ARCHITECTURE.md — Doctor, dual-truth, verified recovery (Phases 1–3).
• Bake-off method: docs/BAKE-OFF.md — pinned competitors + scenarios + dated results.
• Agent skills toolkit: docs/AGENT-SKILLS.md — allowlist + selective install; catalog browse-only (not bulk installs).
• Historical technical dump: docs/TECHNICAL.md — demoted; prefer CHANGELOG + code for shipped 0.x, ARCH for Doctor target.
• Execution bible: docs/EXECUTION.md · GTM/publish: docs/GTM-PUBLISH.md.
• Historical raise notes: docs/PRODUCT-DECISION.md (superseded for identity by STRATEGY-THESIS).
• Cloud self-host: packages/cloud/README.md.
• Validation notes: docs/CUSTOMER-VALIDATION.md.

See CHANGELOG.md.

Ship checklist (maintainers)

Progress board: docs/STATUS.md. Staged train + soak: docs/RELEASE.md. Pre-ship QA: docs/TESTING.md. Marketing sync + release map (0.5.7 → 0.5.9 → 0.6.0): docs/GTM-PUBLISH.md. Claims: docs/STRATEGY-THESIS.md.

0. Complete RELEASE.md hard gates and TESTING.md SIGN-OFF.md READY for this version (do not skip soak / collapse Unreleased into one blast).
1. Confirm the cut matches the release map (do not mix Doctor UI + verify + win in one patch without re-scoping the map).
2. Record/update the live clip in docs/media/GIF-RECORDING.md when the failure→Fix→verify story changed; put it in images/demo.gif before announce.
3. Bump package.json version (maintainer only) + move CHANGELOG Unreleased → versioned section (include Marketing claim-stage line from GTM template).
4. Update README / store description only for user-visible deltas; Open VSX link stays primary for Cursor.
5. npm test && npx vsce package — confirm vsce ls has no test/, *.local.md, launch/, .agents/ (npm test includes lint + Prettier).
6. Set GitHub secrets: VSCE_PAT, OVSX_PAT (see CONTRIBUTING.md).
7. ./scripts/ship-release.sh or push tag v* to run release.yml (same VSIX → Marketplace + Open VSX). Script waits for CI (ci.yml) green via scripts/wait-ci.sh — do not stop at Release-only green.
8. G0 smoke on published Cursor (Open VSX), then post launch/ drafts — claim stage must match thesis for this version.

export VSCE_PAT=... OVSX_PAT=...   # one-time
./scripts/ship-release.sh

License

MIT — see LICENSE.

Security: see SECURITY.md.