mcp-health

name	mcp-health
description	Validates MCP server connectivity and health. Checks stdio and http MCP servers for availability, reports connection status, and provides fallback guidance. Triggers on: mcp health, check mcp, validate mcp, mcp status, mcp connectivity.

MCP Health

Validates MCP server connectivity and health status for local stdio and remote http MCP servers.

Preloaded Skills

Always load before analysis:

• [skill:dotnet-advisor] -- routing and context

Usage

# Check all MCP servers
[mcp-health:check-all]

# Check specific MCP
[mcp-health:check microsoftdocs-mcp]

# Get health report
[mcp-health:report]

MCP Server Types

stdio Servers (Local)

Launch local processes via stdio transport:

• serena -- Semantic code analysis (Language Server Protocol)
• context7 -- Library documentation lookup

http Servers (Remote)

Connect to remote APIs via HTTP:

• microsoftdocs-mcp -- Microsoft Learn documentation
• deepwiki -- DeepWiki MCP server
• github -- GitHub API operations

Health Check Methods

For stdio Servers

# Check if command exists and is executable
which uvx || which npx

# Test stdio connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  uvx --from serena-mcp server 2>&1 | head -5

For http Servers

# Test HTTP connectivity
curl -s -o /dev/null -w "%{http_code}" https://learn.microsoft.com/api/mcp/health
curl -s -o /dev/null -w "%{http_code}" https://mcp.deepwiki.com/health

Validation Script

Add to session start hooks:

# Inline mcp-health-check.sh: Validate MCP servers
set -uo pipefail

MCP_CONFIG="${MCP_CONFIG:-.rulesync/mcp.json}"
[ ! -f "$MCP_CONFIG" ] && exit 0

# Check if jq is available
if ! command -v jq >/dev/null 2>&1; then
  echo "{\"warning\":\"jq not found - skipping MCP health check\"}"
  exit 0
fi

# Extract and validate MCP servers
FAILED_MCP=""

while IFS= read -r mcp_name; do
  mcp_type=$(jq -r ".mcpServers.\"$mcp_name\".type" "$MCP_CONFIG" 2>/dev/null || echo "")

  case "$mcp_type" in
    http)
      url=$(jq -r ".mcpServers.\"$mcp_name\".url" "$MCP_CONFIG" 2>/dev/null)
      if [ -n "$url" ]; then
        if ! curl -s --connect-timeout 5 -o /dev/null "$url/health" 2>/dev/null; then
          FAILED_MCP="$FAILED_MCP $mcp_name"
        fi
      fi
      ;;
    stdio)
      # Check if command exists
      cmd=$(jq -r ".mcpServers.\"$mcp_name\".command" "$MCP_CONFIG" 2>/dev/null)
      if ! command -v "$cmd" >/dev/null 2>&1; then
        # Check common package managers
        case "$cmd" in
          uvx) command -v uvx || command -v pipx || FAILED_MCP="$FAILED_MCP $mcp_name" ;;
          npx) command -v npx || FAILED_MCP="$FAILED_MCP $mcp_name" ;;
        esac
      fi
      ;;
  esac
done < <(jq -r '.mcpServers | keys[]' "$MCP_CONFIG" 2>/dev/null || true)

if [ -n "$FAILED_MCP" ]; then
  echo "{\"warning\":\"MCP servers unavailable:$FAILED_MCP\"}"
else
  echo "{\"status\":\"healthy\"}"
fi

exit 0

Health Report Format

{
  "timestamp": "2026-02-28T10:45:00Z",
  "servers": {
    "serena": {
      "type": "stdio",
      "status": "healthy",
      "command": "uvx",
      "available": true
    },
    "microsoftdocs-mcp": {
      "type": "http",
      "status": "healthy",
      "url": "https://learn.microsoft.com/api/mcp",
      "latency_ms": 45
    },
    "context7": {
      "type": "http",
      "status": "healthy",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "summary": {
    "total": 5,
    "healthy": 4,
    "unavailable": 1
  }
}

Troubleshooting

stdio Server Issues

Problem: Command not found (uvx, npx)

Solutions:

# Install uvx via pipx
pipx install uvx

# Install npx (comes with Node.js)
npm install -g npx

# Or use npm directly for npx packages
npm install -g @anthropic-ai/mcp-server-fetch

Problem: MCP server crashes immediately

Solutions:

• Check MCP server logs: --verbose flag
• Verify environment variables in MCP config
• Update MCP server: pipx upgrade serena-mcp

http Server Issues

Problem: Connection timeout

Solutions:

• Check network connectivity: curl -I <mcp-url>
• Verify firewall/proxy settings
• Check MCP service status page

Problem: 401 Unauthorized

Solutions:

• Verify API tokens in .env or environment
• Check token expiration
• Regenerate tokens if needed

Fallback Behavior

When MCP servers are unavailable:

1. graceful degradation -- Continue without MCP features
2. local caching -- Use cached MCP responses if available
3. alternative sources -- Fall back to web search or local docs
4. user notification -- Inform user of unavailable features

Integration

With Hooks

Add to .rulesync/hooks.json:

{
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "command": "# MCP health check script here",
        "timeout": 30
      }
    ]
  }
}

With Skills

Reference in skills that depend on MCP:

## Preloaded Skills

- [skill:mcp-health] -- validate MCP availability
- [skill:microsoft-learn-mcp] -- query Microsoft documentation

References

• MCP Specification
• [skill:dotnet-observability] -- for health metrics export
• [skill:dotnet-resilience] -- for retry patterns