mcp-health

---
name: mcp-health
description: Check the health of all MCP server connections in the current Claude Code session. Use when the user says "check MCP", "are my servers connected", "why is Telegram not working", "MCP health", "connection issues", "messages not coming through", "is the bot connected", "check connections", or when experiencing any MCP-related connectivity problems. Also use proactively when starting a session with channels/plugins to verify everything is running correctly.
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Glob
---

# /mcp-health — MCP Server Connection Health Check

Arguments passed: `$ARGUMENTS`

## Argument Handling

Parse `$ARGUMENTS` to determine scope:

- **No arguments** (empty or "all") → check ALL MCP servers (default)
- **"quick"** → check all, dashboard only, no fixes
- **"fix"** → check all, automatically resolve issues
- **One or more server names** (e.g., "chrome", "telegram", "chrome, telegram") → check ONLY those servers

Server name matching is case-insensitive. Map common names to their MCP prefixes:
- `chrome` → `mcp__claude-in-chrome__*` tools
- `telegram` → `mcp__plugin_telegram_telegram__*` tools / telegram bun process
- `playwright` → `mcp__plugin_playwright_playwright__*` tools
- `memory` → `mcp__memory__*` tools
- `voicemode` → `mcp__voicemode__*` tools
- `codex` → `mcp__codex-cli__*` tools
- `pubmed` → `mcp__claude_ai_PubMed__*` tools

If arguments are server names, **skip discovery** (Step 1) and jump straight to checking only the named servers. If no arguments or "all", run full discovery.

## Workflow

### Step 1: Discover MCP Servers (skip if specific servers were requested)

Find all configured MCP servers:

```bash
# Check for MCP config files
find ~/.claude -name ".mcp.json" -o -name "mcp.json" 2>/dev/null

# Check plugin cache for MCP configs
find ~/.claude/plugins -name ".mcp.json" 2>/dev/null

# List running MCP-related processes
ps aux | grep -E '(bun|node).*(server|mcp)' | grep -v grep
```

### Step 1b: Discover Non-Process MCP Servers

Some MCP servers don't run as local processes — they connect via browser extensions, HTTP, or other transports. Check for these too:

```bash
# Chrome MCP (browser extension) — check if tools are available
# Try loading a chrome MCP tool to see if the extension is connected
# If mcp__claude-in-chrome__* tools are in the available tools list, it's connected

# Check for any HTTP-based MCP servers in config files
grep -r "http" ~/.claude/plugins/cache/*/.*mcp.json 2>/dev/null | head -10

# Check for voicemode or other non-process MCP servers
ps aux | grep -iE '(voicemode|chrome|claude-in)' | grep -v grep
```

For Chrome MCP specifically: attempt to call `mcp__claude-in-chrome__tabs_context_mcp`. If it responds, the extension is connected. If it errors, report it as DOWN.

### Step 2: Check Each Server

For each discovered MCP server:

**Process-Based Servers (bun/node):**
- Is the process running?
- What's its CPU and memory usage?
- How long has it been running?
- Is its parent process alive (or is it orphaned)?

**Extension/HTTP-Based Servers (Chrome MCP, etc.):**
- Can you call a basic tool? (e.g., tabs_context_mcp for Chrome)
- Is the browser running?
- Report connection status based on tool availability

**Connection Health:**
- Check stdin/stdout file descriptors — are pipes intact?
- Is the process responsive or spinning?

**Conflict Detection:**
- Are there multiple instances of the same server?
- For Telegram: check for 409 Conflict patterns (multiple polling consumers)
- For any bot: check if another service is using the same token/credentials

### Step 3: Check Channel-Specific Health

**Telegram (if configured):**
```bash
# Check access config
cat ~/.claude/channels/telegram/access.json 2>/dev/null

# Check for token
grep -c "TELEGRAM_BOT_TOKEN" ~/.claude/channels/telegram/.env 2>/dev/null

# Check for zombie approvals
ls ~/.claude/channels/telegram/approved/ 2>/dev/null

# Check inbox size
du -sh ~/.claude/channels/telegram/inbox/ 2>/dev/null
```

### Step 4: Report

Present a health dashboard:

```
MCP Health Check
================

Server: telegram
  Process:    PID 189375 (bun server.ts)
  Status:     RUNNING
  CPU:        0.2%
  Memory:     93MB
  Uptime:     1h 23m
  Parent:     ALIVE (claude PID 188176)
  Pipes:      INTACT
  Conflicts:  NONE
  Health:     HEALTHY

Server: [other]
  ...

Overall: X/Y servers healthy

Issues Found:
  - [any problems detected]

Recommendations:
  - [suggested fixes]
```

Status levels:
- **HEALTHY** — Running, low CPU, intact pipes, no conflicts
- **DEGRADED** — Running but high CPU, or competing instances detected
- **ZOMBIE** — Orphaned process, broken pipes, should be killed
- **DOWN** — Not running, needs restart
- **CONFLICT** — Multiple consumers competing for same resource

### Step 5: Offer Fixes

For any non-healthy servers:
- ZOMBIE → offer to kill (link to /zombie-hunter)
- DOWN → suggest restart steps
- CONFLICT → identify competing processes and suggest resolution
- DEGRADED → diagnose root cause and suggest fix

## Special Modes

- `$ARGUMENTS` = "fix" → check all servers AND automatically resolve issues (kill zombies, report what was fixed)
- `$ARGUMENTS` = "quick" → check all servers, dashboard only, no fix offers