Health Monitor MCP Server

health-monitor-mcp

MCP server health monitoring, uptime tracking, Azure DevOps pipeline status, and alert evaluation through natural-language tools.

What This Does

health-monitor-mcp keeps a registry of the MCP servers you care about, performs real MCP handshakes against them, records health history in SQLite, and reports uptime, latency, and alert thresholds back through MCP tools. It also tracks Azure DevOps pipelines so app health and delivery health can be checked from the same place.

Quick Start

The first public npm release target is health-monitor-mcp@1.0.0. If npm still returns E404, the publish gate has not completed yet.

npm install -g health-monitor-mcp
health-monitor-mcp --version

Example desktop MCP client entry after installing the package:

{
  "name": "health-monitor-mcp",
  "version": "1.0.0",
  "mcpName": "io.github.oaslananka/health-monitor-mcp",
  "description": "Monitor MCP server health, uptime, response times, and Azure DevOps pipelines",
  "transport": "stdio",
  "command": "health-monitor-mcp",
  "args": []
}

Tools Reference

Azure DevOps Integration

Register a pipeline group with an org, project, pipeline names, and a PAT:

register_azure_pipelines name="health-monitor-mcp" organization="oaslananka" project="open-source" pipeline_names=["Health Monitor CI","Publish npm"] pat_token="..."

PAT tokens are encrypted in the local SQLite database with AES-256-GCM when HEALTH_MONITOR_ENCRYPTION_KEY is set. Local insecure storage is available only when HEALTH_MONITOR_ALLOW_INSECURE_PAT_STORAGE=1 is explicitly set. See credential storage notes.

Alert Configuration

Use set_alert to configure one server:

Alerts are evaluated inline by check_server, check_all, and get_dashboard. Webhook delivery is planned for v1.1, and no webhook MCP tool is shipped in v1.0.x.

Data Storage

• Default database path: ~/.mcp-health-monitor/health.db
• Override path: HEALTH_MONITOR_DB=/custom/path/health.db
• Optional background scheduler: HEALTH_MONITOR_AUTO_CHECK=1
• HTTP MCP endpoint token: HEALTH_MONITOR_HTTP_TOKEN=...
• HTTP bind host: HOST=127.0.0.1 by default
• Remote-safe HTTP profile: HEALTH_MONITOR_PROFILE=remote-safe
• Remote HTTP Origin allowlist: HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example
• Optional stateful HTTP sessions: HEALTH_MONITOR_HTTP_STATEFUL_SESSIONS=1
• Stateful HTTP session TTL: HEALTH_MONITOR_HTTP_SESSION_TTL_MS=1800000 by default
• Stateful HTTP session cap: HEALTH_MONITOR_HTTP_MAX_SESSIONS=100 by default
• Local stdio checks opt-in: HEALTH_MONITOR_ALLOW_STDIO=1
• Optional stdio command allowlist: HEALTH_MONITOR_STDIO_ALLOWLIST=node,npx
• HTTP server health endpoint: GET /health

Configuration is environment-variable driven; use the variables above directly in your shell, service manager, or MCP client environment block. Stdio monitoring launches local child processes and is disabled unless HEALTH_MONITOR_ALLOW_STDIO=1 is set or an embedding application explicitly enables it through runtime policy. Keep the executable in command and put arguments in args; for example, use command="npx" args=["mcp-debug-recorder"].

The DB uses WAL mode on file-backed databases and applies schema migrations automatically on startup.

Docker

Build and run:

docker build -t health-monitor-mcp .
docker run --rm health-monitor-mcp node dist/mcp.js --version

HTTP mode binds to loopback by default. For a remote HTTP deployment, require a bearer token, the remote-safe profile, and an Origin allowlist:

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e HEALTH_MONITOR_PROFILE=remote-safe \
  -e HEALTH_MONITOR_HTTP_TOKEN=change-me \
  -e HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \
  health-monitor-mcp
curl -X POST \
  --oauth2-bearer "$HEALTH_MONITOR_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  http://127.0.0.1:3000/mcp

Development

corepack enable
corepack prepare pnpm@11.0.9 --activate
pnpm install --frozen-lockfile
pnpm run build
pnpm test
pnpm run test:integration
pnpm run lint
pnpm run lint:test
pnpm run format:check
pnpm run test:coverage
pnpm run docs:api:check
pnpm run ci

Runtime support targets Node 24 LTS or newer. CI, Docker, package metadata, and local development commands are aligned to Node >=24.

Architecture

High-level module map:

• src/app.ts: MCP tool registration and response formatting
• src/checker.ts: Live MCP connectivity probes with retry/backoff
• src/registry.ts: SQLite read/write paths for servers, checks, and pipeline records
• src/db.ts + src/migrations.ts: Connection setup and schema upgrades
• src/server-http.ts + src/mcp.ts: HTTP and stdio entrypoints for local MCP clients and packaged CLI usage
• src/scheduler.ts: Optional background auto-check loop

More detail lives in architecture.md. Decision rationale lives in docs/adr, and generated API docs live in docs/api.

Roadmap

Detailed milestone planning lives in ROADMAP.md.

• v1.0: Core monitoring, uptime, alerts, Azure pipelines, Markdown reports
• v1.1: Webhook notifications for Slack, Discord, and custom endpoints
• v1.2: Multi-provider pipeline and generic HTTP monitoring
• v2.0: Multi-user support and optional external secret-provider integrations

Security

Read SECURITY.md for vulnerability reporting and docs/security.md for implementation-specific storage details.

Contributing

See contributing.md for setup, standards, and PR expectations. Governance, triage labels, and maintainer response targets are documented in governance.md. Usage questions belong in GitHub Discussions; tracked work should use the repository issue forms.

License

MIT

Agent plugin and runtime configuration

This repository owns the product-level agent plugin, MCP runtime configuration, and product-specific skills for health-monitor-mcp. The central agent-tools repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server package.

Validate plugin packaging locally:

claude plugin validate .