# FORGE-mcp-lifeguard

> Health probe and auto-recovery for constitutional federation MCP servers

- Skill: `ariffazil/forge-mcp-lifeguard` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ariffazil/forge-mcp-lifeguard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariffazil/forge-mcp-lifeguard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ariffazil (https://skillmd.com/u/ariffazil)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ariffazil/forge-mcp-lifeguard

---

## When to Use

Use when:
1. An MCP server returns connection refused, timeout, or 5xx
2. OpenClaw logs show `[bundle-mcp] failed to start server`
3. Model fallback chain is failing (DeepSeek 402, Kimi unknown model, Ollama cold-start)
4. You need a federation MCP status dashboard

## MCP Endpoint Map

| Node | URL | Transport | Expected |
|------|-----|-----------|----------|
| arifOS | http://127.0.0.1:8080/mcp | streamable-http | 200 / JSON |
| GEOX | http://127.0.0.1:8081/mcp | streamable-http | 405 (POST only) |
| WEALTH | http://127.0.0.1:8082/mcp | streamable-http | JSON-RPC error |
| WELL | http://127.0.0.1:8083/mcp | streamable-http | JSON-RPC error |

> **Note:** WEALTH and WELL return JSON-RPC errors on GET — this is normal. A connection refused or timeout is the real failure signal.

## Health Probe Commands

### Quick Pulse Check
```bash
for port in 8080 8081 8082 8083; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "http://127.0.0.1:${port}/mcp" || echo "000")
  echo "Port $port: HTTP $code"
done
```

### Deep Probe with Response Time
```bash
for port in 8080 8081 8082 8083; do
  rt=$(curl -s -o /dev/null -w "%{time_total}" --max-time 5 "http://127.0.0.1:${port}/mcp" || echo "999")
  echo "Port $port: ${rt}s"
done
```

### Auto-Restart Dead MCPs
```bash
# Map ports to containers
mcp_map=(
  "8080:arifosmcp"
  "8081:geox_eic"
  "8082:wealth-organ"
  "8083:well"
)

for entry in "${mcp_map[@]}"; do
  port=${entry%%:*}
  container=${entry##*:}
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://127.0.0.1:${port}/mcp" || echo "000")
  if [ "$code" = "000" ] || [ "$code" = "502" ] || [ "$code" = "503" ]; then
    docker restart "$container"
    echo "$(date -Iseconds) RESTARTED $container (port $port, code $code)"
  fi
done
```

## Model Fallback Chain Monitor

### Ping Model Providers
```bash
# MiniMax
curl -s https://api.minimax.io/v1/models -H "Authorization: Bearer $MINIMAX_API_KEY" --max-time 5 | grep -q "MiniMax" && echo "MiniMax: OK" || echo "MiniMax: FAIL"

# DeepSeek
curl -s https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY" --max-time 5 | grep -q "deepseek" && echo "DeepSeek: OK" || echo "DeepSeek: FAIL"

# Ollama local
curl -s http://127.0.0.1:11434/api/tags --max-time 5 | grep -q "qwen2.5:7b" && echo "Ollama: OK" || echo "Ollama: FAIL"
```

## Alert Conditions

| Condition | Action |
|-----------|--------|
| MCP HTTP 000/502/503 | Auto-restart container + log |
| MCP response > 3s | WARN in heartbeat |
| Model provider 401/402 | Disable from fallback chain + alert |
| Ollama cold-start > 15s | Pre-warm model via `/api/generate` |

## Pre-Warm Ollama (Avoid Cold-Start)

```bash
curl -s http://127.0.0.1:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen2.5:7b","prompt":"warmup","stream":false,"options":{"num_predict":1}}' \
  --max-time 30 > /dev/null
echo "Ollama warmed"
```

## Rules

1. **Never restart Vault999** — append-only ledger, human ack required
2. **Restart one MCP at a time** — avoid federation cascade
3. **Log to `~/.openclaw/workspace/logs/mcp-lifeguard.log`**
4. **Disable dead models** — don't let 402s burn event loop cycles
5. **Pre-warm Ollama** on gateway startup if it's in fallbacks