mcp-health-monitor

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

What This Does

mcp-health-monitor 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

Run the monitor over stdio:

npx -y mcp-health-monitor

Example Claude Desktop or VS Code MCP entry:

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

Tools Reference

Tool	Purpose	Typical prompt
register_server	Save an MCP server to monitor	Register https://example.com/mcp as prod-gateway
check_server	Run a live health check for one server	Check prod-gateway now
check_all	Check all registered servers	Check all my MCP servers
get_uptime	Return uptime plus latency stats	Show 24h uptime for prod-gateway
get_dashboard	Return JSON dashboard data	Give me a 24h dashboard
get_report	Return a Markdown report	Generate a Markdown health report for 24h
list_servers	Show registered servers	List all monitored servers
unregister_server	Remove a server	Stop monitoring local-debugger
set_alert	Configure thresholds	Alert if prod-gateway exceeds 500ms or drops below 99% uptime
get_monitor_stats	Show monitor-level stats	How many checks has the monitor recorded?
register_azure_pipelines	Register Azure pipeline groups	Track CI and Publish pipelines for my repo
check_pipeline_status	Read latest Azure pipeline runs	Check pipeline status for my release group
get_pipeline_logs	Fetch Azure build logs	Show the failed logs for the latest Publish build
check_all_projects	Combine MCP and Azure health	Check all projects

Azure DevOps Integration

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

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

PAT tokens are stored as base64 in the local SQLite database for v1.0. This is encoding, not encryption. See credential storage notes.

Alert Configuration

Use set_alert to configure one server:

Field	Meaning
max_response_time_ms	Alert when a check exceeds this latency
min_uptime_percent	Alert when the selected uptime window drops below this value
consecutive_failures_before_alert	Alert after this many non-up results in a row

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 server health endpoint: GET /health
• Example configuration: .env.example

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

Docker

Build and run:

docker build -t mcp-health-monitor .
docker run --rm -p 3000:3000 -e HEALTH_MONITOR_AUTO_CHECK=1 mcp-health-monitor

Then check:

curl http://localhost:3000/health

Development

npm install
npm run build
npm test
npm run test:integration
npm run lint
npm run lint:test
npm run format:check

Use npx --yes -p node@20.19.0 -p npm@10.8.2 npm <command> on workstations where the default Node runtime is newer than the project target.

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
• src/scheduler.ts: Optional background auto-check loop

More detail lives in architecture.md.

Roadmap

Detailed milestone planning lives in ROADMAP.md.

• [x] 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: Encrypted PAT storage and multi-user support

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.

License

MIT