Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(ops-mcp): authed probes + headless fix agent instead of vague notifications (#672)

hypehouseagencyce29a7b70480
diff --git a/claude-ops/scripts/ops-mcp-fixer.sh b/claude-ops/scripts/ops-mcp-fixer.sh
new file mode 100755
index 00000000..e5c87dff
--- /dev/null
+++ b/claude-ops/scripts/ops-mcp-fixer.sh
@@ -0,0 +1,125 @@
+#!/bin/bash
+# ops-mcp-fixer.sh — dispatched by ops-mcp-watchdog.py when an MCP degrades.
+# Spawns a headless Claude agent that diagnoses and repairs the degraded MCP(s).
+# Only when the fix fails (or the hourly budget is spent) does the owner get an
+# INFORMATIVE desktop notification (server name + cause + suggested action) —
+# never a vague "N MCP(s) need attention".
+#
+# Usage: ops-mcp-fixer.sh '<json array of {name,state,detail}>'
+# Guards: lock dir (no concurrent runs, stale >30 min reclaimed),
+# max 2 fixer runs per hour (prevents agent loops).
+#
+# Env:
+# MCP_FIXER_MAX_RUNS_PER_HOUR default 2
+# MCP_FIXER_MAX_TURNS default 60
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+PAYLOAD="${1:-[]}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STATE_DIR="$HOME/.claude/state/mcp-watchdog"
+LOCK_DIR="$STATE_DIR/fixer.lock"
+BUDGET_FILE="$STATE_DIR/fixer-runs.log"
+LOG="$STATE_DIR/fixer.log"
+MAX_RUNS="${MCP_FIXER_MAX_RUNS_PER_HOUR:-2}"
+MAX_TURNS="${MCP_FIXER_MAX_TURNS:-60}"
+mkdir -p "$STATE_DIR"
+
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+log() { echo "$(ts) [ops-mcp-fixer] $*" >> "$LOG"; }
+
+notify() { # $1=title $2=message — informative, includes server names
+ local t="${1//\"/'}" m="${2//\"/'}"
+ if command -v osascript >/dev/null 2>&1; then
+ osascript -e "display notification \"${m:0:220}\" with title \"${t:0:60}\" sound name \"Glass\"" >/dev/null 2>&1
+ elif command -v notify-send >/dev/null 2>&1; then
+ notify-send "$t" "${m:0:220}" >/dev/null 2>&1
+ fi
+}
+
+SUMMARY=$(python3 - "$PAYLOAD" <<'PY' 2>/dev/null
+import json, sys
+try:
+ items = json.loads(sys.argv[1])
+ print("; ".join(f"{i['name']}: {i['state']}" + (f" ({i.get('detail','')[:40]})" if i.get('detail') else "") for i in items))
+except Exception:
+ print("unknown MCP degradation")
+PY
+)
+[ -z "$SUMMARY" ] && SUMMARY="unknown MCP degradation"
+
+# ── Lock: no concurrent fixers. Reclaim stale locks (>30 min). ──
+if [ -d "$LOCK_DIR" ]; then
+ if [ -n "$(find "$LOCK_DIR" -maxdepth 0 -mmin +30 2>/dev/null)" ]; then
+ rm -rf "$LOCK_DIR"; log "reclaimed stale lock"
+ else
+ log "fixer already running — skip ($SUMMARY)"; exit 0
+ fi
+fi
+mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+trap 'rm -rf "$LOCK_DIR"' EXIT
+
+# ── Budget: max N runs per hour ──
+NOW=$(date +%s)
+if [ -f "$BUDGET_FILE" ]; then
+ RECENT=$(awk -v now="$NOW" '$1 > now-3600' "$BUDGET_FILE" | wc -l | tr -d ' ')
+ if [ "$RECENT" -ge "$MAX_RUNS" ]; then
+ log "hourly budget spent ($MAX_RUNS runs) — notifying instead of fixing ($SUMMARY)"
+ notify "MCP degraded — fixer budget spent" "$SUMMARY — check /ops:ops-mcp"
+ exit 0
+ fi
+fi
+echo "$NOW" >> "$BUDGET_FILE"
+tail -20 "$BUDGET_FILE" > "$BUDGET_FILE.tmp" && mv "$BUDGET_FILE.tmp" "$BUDGET_FILE"
+
+CLAUDE_BIN=$(command -v claude || echo "$HOME/.local/bin/claude")
+if [ ! -x "$CLAUDE_BIN" ]; then
+ log "claude binary not found — notifying instead"
+ notify "MCP degraded" "$SUMMARY — claude CLI not found, fix manually"
+ exit 1
+fi
+
+log "fixer agent starting for: $SUMMARY"
+
+PROMPT="You are the automated MCP fixer on this machine (headless, no user present). The ops-mcp-watchdog reports these degraded MCP server(s): $PAYLOAD
+
+Approach:
+1. Read ~/.claude/state/mcp-watchdog/state.json and the last 40 lines of ~/.claude/state/mcp-watchdog/run.log for context.
+2. Common causes to check, in order of likelihood:
+ - Local gateway MCPs (URLs on 127.0.0.1/localhost): is the backing process/service running? Check launchd (macOS) / systemd (Linux) services and restart only the one you have determined to be the cause. A corrupt npx cache (~/.npm/_npx) is a known cause for npx-launched gateways — clearing only the affected package's cache dir is allowed.
+ - Expired OAuth tokens: token caches live in ~/.mcp-auth/mcp-remote-*/ and in the OS keychain under 'Claude Code-credentials' (mcpOAuth). A refresh usually happens automatically on next session start — only intervene if clearly stuck.
+ - Config issues: the server's entry in ~/.claude.json (key mcpServers) — headers, URL, wrapper script paths.
+3. Fix the root cause. Never restart services speculatively.
+4. Verify: re-run python3 $SCRIPT_DIR/ops-mcp-watchdog.py and confirm the affected servers probe healthy.
+5. ONLY if it still fails after 2 attempts: send exactly one desktop notification (osascript on macOS, notify-send on Linux) naming each server, the cause, and the concrete manual action (max 200 chars). On success: NO notification.
+6. Write a 1-3 line summary of what you did to ~/.claude/state/mcp-watchdog/fixer-last-result.txt
+
+Hard limits: delete nothing outside npx caches, never enter passwords, no browser logins, no outbound messages (mail/chat/SMS)."
+
+"$CLAUDE_BIN" -p "$PROMPT" --dangerously-skip-permissions --max-turns "$MAX_TURNS" >> "$LOG" 2>&1
+RC=$?
+log "fixer agent done (exit $RC)"
+
+# ── Independent verification (never trust agent claims blindly) ──
+sleep 5
+STILL_BROKEN=$(python3 - "$PAYLOAD" <<'PY' 2>/dev/null
+import json, sys, pathlib
+try:
+ names = [i["name"] for i in json.loads(sys.argv[1])]
+ state = json.loads((pathlib.Path.home() / ".claude/state/mcp-watchdog/state.json").read_text())
+ bad = [f"{n}: {state[n]['state']}" for n in names if n in state and state[n].get("state") != "healthy"]
+ print("; ".join(bad))
+except Exception:
+ print("")
+PY
+)
+
+if [ -n "$STILL_BROKEN" ] && [ "$RC" -ne 0 ]; then
+ log "still broken after fixer: $STILL_BROKEN"
+ notify "MCP still degraded after auto-fix" "$STILL_BROKEN — check /ops:ops-mcp"
+elif [ -n "$STILL_BROKEN" ]; then
+ log "fixer finished but state not yet healthy: $STILL_BROKEN (agent may have notified itself)"
+else
+ log "verified recovered: $SUMMARY"
+fi
+exit 0
diff --git a/claude-ops/scripts/ops-mcp-watchdog.py b/claude-ops/scripts/ops-mcp-watchdog.py
index ab9651b2..ad700462 100755
--- a/claude-ops/scripts/ops-mcp-watchdog.py
+++ b/claude-ops/scripts/ops-mcp-watchdog.py
@@ -18,7 +18,13 @@ Every cron tick:
Env:
MCP_WATCHDOG_AUTO_REFRESH=1 (default 1) — attempt silent OAuth refresh
when token_expired. Set 0 to disable.
- MCP_WATCHDOG_NOTIFY=1 (default 1) — fire WhatsApp on new degradations.
+ MCP_WATCHDOG_NOTIFY=1 (default 1) — act on new degradations.
+ MCP_WATCHDOG_FIX_AGENT=1 (default 1) — on degradation, dispatch the
+ headless fix agent (scripts/ops-mcp-fixer.sh)
+ instead of notifying. Notifications only fire
+ when the agent is disabled, missing, or fails —
+ and then informatively (name + cause), never
+ a bare "N MCP(s) need attention".
POCKET_STATE_DIR for WhatsApp config lookup
MCP_WATCHDOG_PROBE_TIMEOUT default 6s per MCP
@@ -50,6 +56,8 @@ LOG_FILE = STATE_DIR / "run.log"
AUTO_REFRESH = os.environ.get("MCP_WATCHDOG_AUTO_REFRESH", "1") == "1"
AUTO_REAUTH = os.environ.get("MCP_WATCHDOG_AUTO_REAUTH", "1") == "1"
NOTIFY = os.environ.get("MCP_WATCHDOG_NOTIFY", "1") == "1"
+FIX_AGENT = os.environ.get("MCP_WATCHDOG_FIX_AGENT", "1") == "1"
+FIXER_SCRIPT = Path(__file__).resolve().parent / "ops-mcp-fixer.sh"
PROBE_TIMEOUT = int(os.environ.get("MCP_WATCHDOG_PROBE_TIMEOUT", "6"))
REAUTH_SCRIPT = Path(__file__).resolve().parent / "ops-mcp-reauth.py"
@@ -79,6 +87,39 @@ def get_api_key_for(name: str) -> str | None:
return None
+def config_headers(name: str) -> dict:
+ """Static headers from ~/.claude.json mcpServers[name].headers (e.g. a
+ local gateway MCP configured with a Bearer token in its config entry)."""
+ try:
+ d = json.loads((HOME / ".claude.json").read_text())
+ return dict(((d.get("mcpServers") or {}).get(name) or {}).get("headers") or {})
+ except Exception:
+ return {}
+
+
+def keychain_oauth_token(name: str) -> str | None:
+ """Claude Code's own OAuth store: macOS keychain item 'Claude Code-credentials'
+ → mcpOAuth. Keys look like '<serverName>|<hash>'. Skips expired tokens.
+ Without this, HTTP MCPs that Claude Code authenticated natively (not via
+ mcp-remote) probe as 401 forever even though sessions work fine."""
+ try:
+ out = subprocess.run(
+ ["security", "find-generic-password", "-s", "Claude Code-credentials", "-w"],
+ capture_output=True, text=True, timeout=5)
+ if out.returncode != 0:
+ return None
+ entries = json.loads(out.stdout).get("mcpOAuth") or {}
+ for key, entry in entries.items():
+ if key.split("|")[0] == name and entry.get("accessToken"):
+ exp = entry.get("expiresAt") or 0
+ if exp and exp / 1000 < time.time():
+ continue
+ return entry["accessToken"]
+ except Exception:
+ pass
+ return None
+
+
def now_iso() -> str:
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -184,6 +225,16 @@ def probe(url: str, mcp_name: str = "") -> dict:
pass
if tokens and tokens.get("access_token"):
headers["Authorization"] = f"Bearer {tokens['access_token']}"
+ # No mcp-remote token cache? Fall back to (1) static headers from the
+ # server's own config entry, then (2) Claude Code's native OAuth store.
+ # Probing without these reports 401 degradations that sessions never see.
+ if "Authorization" not in headers:
+ for k, v in config_headers(mcp_name).items():
+ headers.setdefault(k, v)
+ if "Authorization" not in headers:
+ kc_tok = keychain_oauth_token(mcp_name)
+ if kc_tok:
+ headers["Authorization"] = f"Bearer {kc_tok}"
body = json.dumps({
"jsonrpc": "2.0", "id": 1, "method": "initialize",
@@ -474,16 +525,30 @@ def main() -> int:
except Exception as e:
log(f"{name}: reauth error: {type(e).__name__}: {e}")
- # Notify on new degradations
+ # New degradations → dispatch the headless fix agent; notify only as fallback
if degraded and NOTIFY:
- bullets = "\n".join(f"• {n} → {s} ({d[:60]})" for n, s, d in degraded)
- macos_notify("MCP degradation", f"{len(degraded)} MCP(s) need attention")
- whatsapp_notify(
- f"⚠️ MCP watchdog — {len(degraded)} server(s) degraded:\n\n{bullets}\n\n"
- f"Run `pocket mcps` for details. Open Claude Code to re-auth via browser, "
- f"or build out the Playwright auto-approver if you want zero-touch."
- )
- log(f"notified about {len(degraded)} degradations")
+ oneliner = "; ".join(f"{n}: {s}" + (f" ({d[:40]})" if d else "") for n, s, d in degraded)
+ dispatched = False
+ if FIX_AGENT and FIXER_SCRIPT.exists():
+ try:
+ payload = json.dumps([
+ {"name": n, "state": s, "detail": d} for n, s, d in degraded])
+ subprocess.Popen(
+ ["bash", str(FIXER_SCRIPT), payload],
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+ start_new_session=True)
+ dispatched = True
+ log(f"dispatched fix agent for: {oneliner}")
+ except Exception as e:
+ log(f"fix agent dispatch failed: {type(e).__name__}: {e}")
+ if not dispatched:
+ bullets = "\n".join(f"• {n} → {s} ({d[:60]})" for n, s, d in degraded)
+ macos_notify("MCP degraded", oneliner[:220])
+ whatsapp_notify(
+ f"⚠️ MCP watchdog — {len(degraded)} server(s) degraded:\n\n{bullets}\n\n"
+ f"Run `pocket mcps` for details, or open Claude Code to re-auth."
+ )
+ log(f"notified about {len(degraded)} degradations: {oneliner}")
if recovered:
log(f"recovered: {', '.join(recovered)}")