Skip to main content
Glama
MCP Health Monitor

MCP Health Monitor

mcp-health-monitor

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

npm version npm downloads License: MIT Node.js

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.

  • 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

Available Tools

14 tools
check_allCheck All ServersB
Read-only

Check health of all registered MCP servers in parallel.

Inputs: timeout_ms, tags.

check_all_projectsCheck All Projects HealthA
Read-only

Check both MCP server health and Azure DevOps pipeline status across all registered projects.

Inputs: timeout_ms.

check_pipeline_statusCheck Azure Pipeline StatusA
Read-only

Get the latest run status of registered Azure DevOps pipelines for one group or all groups.

Inputs: group_name.

check_serverCheck Server HealthC
Read-only

Check the health of a registered MCP server, list tools, and measure response time.

Inputs: name (required), timeout_ms.

get_dashboardGet Health DashboardA
Read-only

Get a dashboard overview of all registered MCP servers with uptime and performance stats.

Inputs: hours, include_tool_stats.

get_monitor_statsGet Monitor StatisticsA
Read-only

Get statistics about the health monitor itself, including database activity.

Inputs: no named parameters.

get_pipeline_logsGet Pipeline LogsA
Read-only

Fetch logs from a specific Azure DevOps build to investigate pipeline failures.

Inputs: group_name (required), pipeline_name (required), build_id, failed_only.

get_reportGet Health Report (Markdown)A
Read-only

Get a human-readable Markdown health report for all servers. Paste directly into chat or docs.

Inputs: hours.

get_uptimeGet Uptime StatisticsA
Read-only

Get uptime history and statistics for a registered MCP server.

Inputs: name (required), hours.

list_serversList Registered ServersC
Read-only

List all registered MCP servers with their current status.

Inputs: tags, status.

register_azure_pipelinesRegister Azure DevOps PipelinesB

Register Azure DevOps pipelines to monitor for CI, publish, and mirror status.

Inputs: name (required), organization (required), project (required), pipeline_names (required), +1 more.

register_serverRegister MCP ServerA

Register an MCP server to monitor. Supports http, sse, and stdio transports.

Inputs: name (required), type (required), url, command, +4 more.

set_alertSet Alert ThresholdsA

Configure alert thresholds for response time, uptime, and consecutive failures.

Inputs: name (required), max_response_time_ms, min_uptime_percent, consecutive_failures_before_alert.

unregister_serverUnregister ServerB
Destructive

Remove a server from monitoring.

Inputs: name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools are clearly distinct: registration, checks, logs, alerts, reports, and stats each target a different concern. However, 'get_dashboard' and 'get_report' overlap significantly (both provide overviews of monitored servers), and 'check_all' vs 'check_all_projects' could be confused by an agent (one covers only servers, the other covers servers plus pipelines).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (register_*, check_*, get_*, set_*, list_*, unregister_*). Even the compound 'check_all_projects' fits the pattern as a verb with a clear object. There are no mixed naming conventions or vague verbs like 'process' or 'execute'.

    Tool Count5/5

    14 tools is well within the ideal 3-15 range. Each tool has a specific purpose in the monitoring domain, and the count supports comprehensive coverage without overwhelming an agent. The tool set is broad enough to cover registration, health checks, pipeline status, logs, reports, alerts, and stats.

    Completeness4/5

    The tool surface covers the core lifecycle: register, check, unregister, get logs, get history, get reports, and set alerts. Minor gaps include lack of explicit update/edit for registered servers or pipelines (e.g., changing transport or platform), and no tool to pause/resume monitoring, but agents can often work around those by re-registering.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors