mcp-validator

MCP Server Health Validator

Generate a bash script at scripts/harness/mcp_health.sh that validates configured MCP servers are reachable. This runs from the SessionStart hook as an informational check (never blocks).

Step 1: Create the health check script

Create scripts/harness/mcp_health.sh and make it executable:

#!/usr/bin/env bash
# SessionStart hook — MCP server health check.
# Informational only — always exits 0.

PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"

# Find settings file
SETTINGS=""
for candidate in "${PROJECT_ROOT}/.claude/settings.local.json" "${PROJECT_ROOT}/.claude/settings.json"; do
  if [ -f "$candidate" ]; then
    SETTINGS="$candidate"
    break
  fi
done

if [ -z "$SETTINGS" ]; then
  # No settings file — nothing to check
  exit 0
fi

# Check if jq is available
if ! command -v jq &>/dev/null; then
  echo "Harn: jq not found — skipping MCP health check." >&2
  exit 0
fi

# Extract MCP server names
SERVERS=$(jq -r '.mcpServers // {} | keys[]' "$SETTINGS" 2>/dev/null)

if [ -z "$SERVERS" ]; then
  exit 0
fi

FAILED=()
CHECKED=0

while IFS= read -r name; do
  CHECKED=$((CHECKED + 1))

  # Check if server has a command
  CMD=$(jq -r --arg n "$name" '.mcpServers[$n].command // empty' "$SETTINGS" 2>/dev/null)
  if [ -n "$CMD" ]; then
    if ! command -v "$CMD" &>/dev/null; then
      FAILED+=("$name")
    fi
    continue
  fi

  # Check if server has a url
  URL=$(jq -r --arg n "$name" '.mcpServers[$n].url // empty' "$SETTINGS" 2>/dev/null)
  if [ -n "$URL" ]; then
    if ! curl -sf --max-time 2 "$URL" >/dev/null 2>&1; then
      FAILED+=("$name")
    fi
    continue
  fi

done <<< "$SERVERS"

if [ ${#FAILED[@]} -eq 0 ]; then
  echo "Harn: All MCP servers reachable." >&2
else
  for name in "${FAILED[@]}"; do
    echo "Harn: MCP server '${name}' unreachable — tools may fail." >&2
  done
fi

exit 0

Step 2: Wire into session-start.sh

If scripts/harness/session-start.sh exists, append the MCP health check call. If it does not exist, create it with: