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.
metadata	{"short-description":"Toolkit guidance for mcp-health"}

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.\"\".command"  2>/dev/null)
       !  -v  >/dev/null 2>&1; 
        
          
          uvx)  -v uvx ||  -v pipx || FAILED_MCP= ;;
          npx)  -v npx || FAILED_MCP= ;;
        
      
      ;;
  
 < <(jq -r   2>/dev/null || )

 [ -n  ]; 
   

   


 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": 
       
    
  
   
     
     
     
  

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