Skip to main content
Glama
health-monitor-mcp

health-monitor-mcp

by oaslananka

health-monitor-mcp

MCP server, CI workflow, and generic HTTP endpoint monitoring with health history, TLS expiry, assertions, diagnostics, and operational reports.

CI codecov Release License: MIT OpenSSF Scorecard Node.js

What This Does

health-monitor-mcp keeps local registries of MCP servers, GitHub Actions workflows, GitLab pipelines, and generic HTTP endpoints. It performs live checks, records bounded evidence in SQLite, evaluates MCP alert thresholds, and returns JSON or Markdown diagnostics suitable for agents and operators.

Supported target transports:

  • Streamable HTTP for current remote MCP servers.

  • SSE for legacy MCP servers.

  • stdio for trusted local executables after explicit opt-in.

  • GitHub Actions workflow runs, failed jobs, and failed steps for public or private repositories.

  • GitLab CI/CD pipelines, failed jobs, stages, refs, commits, URLs, and bounded trace excerpts for GitLab.com or allowlisted self-hosted instances.

  • Generic HTTP/HTTPS endpoints with status, header, body-substring, JSON-value, redirect, latency, and TLS-expiry checks.

Azure DevOps monitoring was retired in v1.1.0. GitHub Actions shipped in v1.2.0 and GitLab CI/CD in v1.3.0; generic HTTP/TLS monitoring completes the current multi-provider feature line.

Related MCP server: DevHelm MCP Server

Quick Start

Run the published package noninteractively with Node.js 24:

npx -y health-monitor-mcp --version

Example MCP client configuration:

{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "health-monitor-mcp"]
    }
  }
}

Tools

Tool

Purpose

Typical prompt

register_server

Register an MCP target

Register inventory-prod

check_server

Run one MCP health check

Check inventory-prod now

register_github_actions

Register a GitHub workflow

Monitor ci.yml in owner/repo

check_github_actions

Check latest GitHub run and failed job/step diagnostics

Check repo-ci now

register_gitlab_pipeline

Register a GitLab project pipeline

Monitor group/project on GitLab

check_gitlab_pipeline

Check latest pipeline and bounded failed-job traces

Check gitlab-ci now

register_http_target

Register a GET-only HTTP/HTTPS endpoint

Monitor the public health endpoint

check_http_target

Check response assertions and TLS expiry

Check service-health now

register_webhook

Register a webhook target for alert delivery

Register alert-webhook for notifications

test_webhook

Send a test payload and return delivery diagnostics

Test alert-webhook delivery

check_all

Check all target kinds with bounded concurrency

Check all production targets

get_uptime

Return MCP uptime and latency history

Show 24h uptime for inventory-prod

get_dashboard

Return a cross-provider JSON dashboard

Give me a 24h dashboard

get_report

Return a cross-provider Markdown report

Generate a 24h health report

list_servers

List registered MCP targets

List monitored MCP servers

list_github_actions

List registered GitHub workflow targets

List monitored workflows

list_gitlab_pipelines

List registered GitLab pipeline targets

List monitored GitLab pipelines

list_http_targets

List registered HTTP targets

List monitored HTTP endpoints

list_webhooks

List registered webhook targets

List webhook targets

unregister_server

Remove an MCP target

Stop monitoring local-debugger

unregister_github_actions

Remove a GitHub target and its history

Stop monitoring repo-ci

unregister_gitlab_pipeline

Remove a GitLab target and its history

Stop monitoring gitlab-ci

unregister_http_target

Remove an HTTP target and its history

Stop monitoring service-health

unregister_webhook

Remove a webhook target and its history

Stop monitoring alert-webhook

set_alert

Configure MCP health thresholds

Alert if inventory-prod exceeds 500ms

get_monitor_stats

Inspect cross-provider monitor activity

How many checks are stored?

Expected configuration mistakes return stable error codes and remediation hints, including SERVER_NOT_FOUND, GITHUB_ACTIONS_TARGET_NOT_FOUND, GITLAB_PIPELINE_TARGET_NOT_FOUND, GITLAB_BASE_URL_NOT_ALLOWED, HTTP_TARGET_NOT_FOUND, HTTP_TARGET_URL_NOT_ALLOWED, NO_SERVERS_REGISTERED, STDIO_DISABLED, STDIO_COMMAND_REJECTED, WEBHOOK_ENCRYPTION_KEY_REQUIRED, WEBHOOK_REGISTRATION_FAILED, and WEBHOOK_NOT_FOUND.

Register Targets

Streamable HTTP:

register_server name="inventory-prod" type="http" url="https://inventory.example.com/mcp" tags=["production","inventory"]

Legacy SSE:

register_server name="legacy-search" type="sse" url="https://search.example.com/sse" tags=["legacy"]

Trusted local stdio:

export HEALTH_MONITOR_ALLOW_STDIO=1
export HEALTH_MONITOR_STDIO_ALLOWLIST=npx,node
register_server name="local-debugger" type="stdio" command="npx" args=["-y","mcp-debug-recorder"] tags=["local"]

The command field must contain one executable only. Put package names and flags in args. Remote-safe runtime profiles always disable stdio.

Register GitHub Actions

Public repositories can be checked without authentication. Private repositories and higher API rate limits require a token with Actions read access:

export GITHUB_TOKEN=your-runtime-secret
register_github_actions name="repo-ci" owner="oaslananka" repository="health-monitor-mcp" workflow="ci.yml" branch="main" token_env="GITHUB_TOKEN" tags=["production","ci"]
check_github_actions name="repo-ci" timeout_ms=5000

Only the environment-variable name in token_env is stored. The token value is read at check time and is never written to SQLite, logs, reports, or tool responses.

Register GitLab Pipelines

Public GitLab.com projects can be checked without authentication. Private projects require a token exposed only through the runtime environment:

export GITLAB_TOKEN=your-runtime-secret
register_gitlab_pipeline name="gitlab-ci" project="group/project" ref="main" token_env="GITLAB_TOKEN" tags=["production","ci"]
check_gitlab_pipeline name="gitlab-ci" timeout_ms=5000

GitLab.com is allowed by default. A self-hosted instance must use an HTTPS origin and be explicitly allowed:

export HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST=https://gitlab.internal.example
register_gitlab_pipeline name="private-gitlab" base_url="https://gitlab.internal.example" project="platform/service" token_env="GITLAB_TOKEN"

Only token_env is persisted. Token values, response bodies, and full traces are never stored or returned. Failed-job trace excerpts are range-requested, sanitized, and bounded.

Register HTTP Targets

Public HTTP and HTTPS endpoints are allowed by default. The provider sends GET requests only and supports bounded status, header, body-substring, JSON scalar, and TLS-expiry assertions:

register_http_target name="service-health" url="https://status.example.com/health" expected_statuses=[200] header_assertions=[{"name":"x-ready","equals":"yes"}] body_contains=["ready"] json_assertions=[{"path":"status","equals":"ready"}] tls_expiry_days=30 tags=["production","http"]
check_http_target name="service-health" timeout_ms=5000

Private, loopback, link-local, and other non-public addresses are blocked. A trusted private origin is available only in the full runtime profile and must be explicitly listed:

export HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST=https://status.internal.example:8443

Every DNS answer and every redirect destination is revalidated. Responses are capped at 262144 bytes; full response bodies and certificate chains are never stored or returned.

Register Webhook Targets

Webhook targets receive alert notifications via HTTPS POST with optional HMAC-SHA256 signing. Secrets are encrypted at rest when HEALTH_MONITOR_WEBHOOK_ENCRYPTION_KEY is configured (32+ characters); otherwise secret registration is rejected.

register_webhook name="alert-webhook" url="https://hooks.example/alerts" secret="webhook-secret" events=["down","alert"] tags=["production","alerts"]
test_webhook name="alert-webhook"

Secrets are never returned in listings or diagnostics—always redacted. Delivery diagnostics include status, latency, HTTP status code, and error message.

Health Checks and Reports

check_server name="inventory-prod" timeout_ms=5000
check_all timeout_ms=5000 tags=["production"]
get_uptime name="inventory-prod" hours=24
get_dashboard hours=24 include_tool_stats=true
get_report hours=24

HEALTH_MONITOR_MAX_CONCURRENCY limits MCP, GitHub Actions, GitLab, and HTTP checks through one shared scheduled and interactive queue. Results preserve MCP-then-GitHub-then-GitLab-then-HTTP registration order even when checks complete out of order.

Alerts

set_alert name="inventory-prod" max_response_time_ms=500 min_uptime_percent=99 consecutive_failures_before_alert=2

Alert findings are evaluated by check_server, check_all, and get_dashboard. Configure webhook targets with register_webhook to receive alert notifications.

Configuration

Variable

Default

Purpose

HEALTH_MONITOR_DB

~/.mcp-health-monitor/health.db

SQLite database path

HEALTH_MONITOR_AUTO_CHECK

0

Enable scheduled checks with 1

HEALTH_MONITOR_RETENTION_DAYS

30

Health-history retention

HEALTH_MONITOR_MAX_CONCURRENCY

5

Scheduled and interactive check concurrency

GITHUB_TOKEN

unset

Optional GitHub Actions read token

GITLAB_TOKEN

unset

Optional GitLab project/pipeline/job read token

HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST

unset

Allowed self-hosted GitLab HTTPS origins

HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST

unset

Private HTTP(S) origins allowed in full profile

HEALTH_MONITOR_ALLOW_STDIO

0

Allow trusted local stdio checks

HEALTH_MONITOR_STDIO_ALLOWLIST

unset

Optional comma-separated executable allowlist

HEALTH_MONITOR_HTTP_TOKEN

unset

Bearer token for POST /mcp

HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST

unset

Allowed remote client origins

HEALTH_MONITOR_HTTP_MAX_BODY_BYTES

1048576

Maximum inbound MCP body

HEALTH_MONITOR_HTTP_BODY_TIMEOUT_MS

15000

Inbound body read timeout

HEALTH_MONITOR_HTTP_STATEFUL_SESSIONS

0

Enable stateful Streamable HTTP sessions

HEALTH_MONITOR_HTTP_SESSION_TTL_MS

1800000

Stateful session TTL

HEALTH_MONITOR_HTTP_MAX_SESSIONS

100

Stateful session cap

HEALTH_MONITOR_WEBHOOK_ENCRYPTION_KEY

unset

32+ char key for encrypting webhook secrets

HEALTH_MONITOR_WEBHOOK_TIMEOUT_MS

5000

Webhook delivery timeout in milliseconds

HTTP Deployment

The server binds to 127.0.0.1 by default. A non-loopback bind requires a remote-safe profile, bearer token, and Origin allowlist.

HOST=0.0.0.0 \
HEALTH_MONITOR_PROFILE=remote-safe \
HEALTH_MONITOR_HTTP_TOKEN=change-me \
HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \
npx -y health-monitor-mcp-http

GET /health is unauthenticated and exposes only status and version. POST /mcp requires Authorization: Bearer <token>.

Docker

Persist /data; otherwise the SQLite database disappears with the container.

docker volume create health-monitor-data

docker run --rm \
  -v health-monitor-data:/data \
  -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 \
  ghcr.io/oaslananka/health-monitor-mcp:latest

Development

The repository pins Node.js 24.18.0 and pnpm 11.14.0 through .mise.toml.

mise trust
mise install
pnpm install --frozen-lockfile
pnpm run ci

Useful gates:

pnpm run build
pnpm run typecheck
pnpm run lint
pnpm run lint:test
pnpm run test:coverage
pnpm run test:integration
pnpm run docs:api:check
pnpm run security:supply-chain
pnpm run check:metadata
pnpm run check:package

Coverage and Test Analytics

Jest remains the blocking coverage gate with repository-local thresholds. The CI validation job runs all unit and integration tests once, writes coverage/lcov.info and reports/junit/junit.xml, and uploads both reports to Codecov. Codecov project and patch statuses start as informational with target: auto and a 1% tolerance, adding pull-request diff coverage, file-level visibility, and failed-test analytics without duplicating the local merge gate.

Codecov Bundle Analysis is intentionally not enabled. This package ships Node.js entrypoints compiled with tsc; it does not currently produce a Rollup, Vite, or Webpack application bundle whose download size is a product metric.

Architecture and Roadmap

Agent Runtime Configuration

This repository owns its product-specific MCP configuration, plugin manifest, and skills:

File

Purpose

.claude-plugin/plugin.json

Claude Code plugin manifest

.mcp.json

Project-local MCP configuration

.codex/config.example.toml

Codex CLI example

.vscode/mcp.example.json

VS Code / Copilot example

opencode.example.jsonc

OpenCode example

skills/

Product-specific monitoring workflows

docs/agent-runtime-config.md

Runtime setup and validation

Security and Contributing

Report vulnerabilities through GitHub Private Vulnerability Reporting. See SECURITY.md and docs/security.md.

Contribution setup and standards are documented in docs/contributing.md. Usage questions belong in GitHub Discussions; actionable work belongs in issues.

License

MIT

Available Tools

22 tools
check_allCheck All TargetsA
Read-only

Check all registered MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets with one bounded concurrency limit. Results preserve MCP-then-GitHub-then-GitLab-then-HTTP registration order; optional tags filter all target kinds.

Inputs: tags, timeout_ms.

check_github_actionsCheck GitHub Actions WorkflowA
Read-only

Check the latest run for a registered GitHub Actions workflow and return failed job and step diagnostics.

Inputs: name (required), timeout_ms.

check_gitlab_pipelineCheck GitLab PipelineA
Read-only

Check the latest registered GitLab pipeline and return failed job, stage, ref, commit, URL, and bounded trace diagnostics.

Inputs: name (required), timeout_ms.

check_http_targetCheck HTTP TargetA
Read-only

Check a registered HTTP target with DNS-pinned SSRF protection, bounded redirects/body reads, response assertions, and TLS-expiry diagnostics.

Inputs: name (required), timeout_ms.

check_serverCheck Server HealthA
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 registered MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets 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_reportGet Health Report (Markdown)A
Read-only

Get a human-readable Markdown health report for MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets. Paste directly into chat or docs.

Inputs: hours.

get_uptimeGet Uptime StatisticsB
Read-only

Get uptime history and statistics for a registered MCP server.

Inputs: name (required), hours.

list_github_actionsList GitHub Actions WorkflowsA
Read-only

List registered GitHub Actions workflow targets and their latest status.

Inputs: tags, status.

list_gitlab_pipelinesList GitLab PipelinesB
Read-only

List registered GitLab pipeline targets and their latest status.

Inputs: tags, status.

list_http_targetsList HTTP TargetsA
Read-only

List registered HTTP targets and their latest status, response, and TLS summary.

Inputs: tags, status.

list_serversList Registered ServersB
Read-only

List all registered MCP servers with their current status.

Inputs: tags, status.

register_github_actionsRegister GitHub Actions WorkflowA

Register a GitHub Actions workflow by owner, repository, and workflow file or ID. Only the token environment-variable name is stored; token values remain in the runtime environment.

Inputs: name (required), owner (required), workflow (required), repository (required), +4 more.

register_gitlab_pipelineRegister GitLab PipelineA

Register a GitLab CI/CD project pipeline. GitLab.com is allowed by default; self-hosted HTTPS origins require HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST. Only the token environment-variable name is stored.

Inputs: name (required), project (required), ref, tags, +3 more.

register_http_targetRegister HTTP TargetA

Register a GET-only HTTP or HTTPS endpoint with status, header, body, JSON, and TLS-expiry assertions. Public networks are allowed by default; private origins require full profile and HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST.

Inputs: no named parameters.

register_serverRegister MCP ServerA

Register an MCP server. Use http for a Streamable HTTP MCP endpoint, sse only for legacy Server-Sent Events servers, and stdio only for a local executable explicitly allowed by runtime policy.

Inputs: no named parameters.

set_alertSet Alert ThresholdsA

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

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

unregister_github_actionsUnregister GitHub Actions WorkflowA
Destructive

Remove a GitHub Actions workflow target and its stored check history.

Inputs: name (required).

unregister_gitlab_pipelineUnregister GitLab PipelineA
Destructive

Remove a GitLab pipeline target and its stored check history.

Inputs: name (required).

unregister_http_targetUnregister HTTP TargetA
Destructive

Remove an HTTP target and its stored check history.

Inputs: name (required).

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.9/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool targets a distinct resource type (MCP server, HTTP target, GitHub Actions, GitLab pipeline) and action (register, list, check, unregister). The cross-cutting tools (check_all, get_dashboard, get_report, get_monitor_stats) have clearly separate purposes, so there is no ambiguity.

    Naming Consistency5/5

    All tool names follow a verb_noun pattern (register, list, check, unregister, get, set) with the resource type clearly stated. Minor singular/plural variations (e.g., list_http_targets vs. register_http_target) are natural and do not break consistency.

    Tool Count5/5

    With 22 tools covering four distinct target types (MCP servers, HTTP, GitHub Actions, GitLab pipelines) plus cross-cutting monitoring and reporting, the count is well-scoped for the server's broad purpose. Each tool earns its place, and the count is not excessive for the feature set.

    Completeness4/5

    The lifecycle for each target type is covered: register, list, check, and unregister. There is no explicit update/edit operation for target configurations (e.g., modifying assertions), but agents can work around this by unregistering and re-registering. Overall, the surface is solid with only minor gaps.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Monitor MCP server health, uptime, response times, and Azure DevOps pipeline status
      14
      12 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for running infrastructure health checks with TIBET provenance. It enables users to define, execute, and audit process health checks with dependency chaining and drift tracking.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP-native health monitoring that probes MCP servers using the list_tools protocol handshake, detects version drift, stores history in SQLite, and generates an HTML dashboard.
      75 npm
      MIT