Meta Agent Tools
PT

Back to the catalog

io.github.dbsectrainer/mcp-server-health-monitor

Health monitoring for all your MCP servers

Open source Open in the app JSON README (API)

About

Health monitoring for all your MCP servers

Details

Kind
MCP servers
Topic
Government & public data
Publisher
dbsectrainer
Origin
official
Category
ferramentas
Transport
local
Version
1.0.0
Open pull requests
15
Last push
2026-04-28T00:49:53Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 03:02:41
Updated
2026-08-29 03:02:41
Origin id
io.github.dbsectrainer/mcp-server-health-monitor

README

# MCP Server Health Monitor

npm `mcp-server-health-monitor` package

MCP-native health monitoring that speaks the protocol, not just HTTP. Instead of pinging a port, it calls `list_tools` on each server — the same handshake your agent uses — so a green status means the server is actually ready to serve MCP requests. All health history stays local in SQLite; no external monitoring service required.

[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting)

## Key features

- **Auto-discovery**: Reads your existing MCP config files (Claude Desktop, Cursor, VS Code) with no extra setup.
- **Non-intrusive probing**: Only calls `list_tools` on target servers — read-only, no side effects.
- **Version drift detection**: Compares tool schemas across checks to detect when a server has been updated.
- **Historical trends**: Stores latency history in SQLite; p50/p95 are computed on-demand from stored history to surface regressions before they become outages.
- **HTML dashboard**: Generates a self-contained health dashboard with uptime sparklines per server.
- **Background polling**: Runs as a daemon so health data is always fresh when you ask for it.

## Why this over generic uptime monitors?

Generic uptime monitors (UptimeRobot, Pingdom, BetterStack) check whether a port is open or an HTTP endpoint returns 200. That's not enough for MCP servers — a server can be running but failing to negotiate the MCP protocol or returning a broken tool schema.

|                        | mcp-server-health-monitor                                   | Generic uptime monitors                    |
| ---------------------- | ----------------------------------------------------------- | ------------------------------------------ |
| Probe method           | MCP `list_tools` call — tests actual protocol               | HTTP ping or TCP port check                |
| Schema drift detection | Detects when tool signatures change between versions        | Not possible without protocol awareness    |
| Config auto-discovery  | Reads Claude Desktop, Cursor, VS Code configs automatically | Manual URL entry per server                |
| Data residency         | Local SQLite; no external service                           | Health data stored in vendor cloud         |
| Cost                   | Free, self-hosted                                           | Free tier limited; paid for history/alerts |

If you want to know that your MCP servers are genuinely healthy — not just "the process is running" — this is the right tool.

## Requirements

- Node.js v20.19 or newer.
- npm.

## Getting started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "mcp-server-health-monitor@latest"]
    }
  }
}
```

> The monitor auto-discovers other MCP servers from the same config file it is registered in. No additional setup required.

### MCP Client configuration

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

## Your first prompt

Enter the following in your MCP client to verify everything is working:

```
Check the health of all my MCP servers.
```

Your client should return a status table showing each server with its current latency and health state.

## Tools

### Health checks (3 tools)

- `health_check_all` — probes all configured servers in parallel via `list_tools`, measures latency, and stores results. Accepts an optional `timeout_ms` parameter (default: 5000).
- `get_server_status` — returns per-server detail including latency, last seen time, 24-hour error count, last error message, and p50/p95 latency percentiles. Requires `server_name`.
- `list_degraded` — filters to servers that are offline or have latency above the threshold. Accepts an optional `latency_threshold` override.

### History (1 tool)

- `get_history` — returns raw health check history for a specific server, ordered most-recent first. Requires `server_name`; accepts optional `limit` (default: 50, max: 500).

### Server registry (2 tools)

- `configure_server` — registers a new MCP server to monitor. Servers added this way are stored in `~/.mcp/extra-servers.json` and merged with auto-discovered servers. Required: `name`, `command`. Optional: `args`, `env`.
- `remove_server` — removes a manually registered server from monitoring. Only affects servers added via `configure_server`; auto-discovered servers are not affected. Requires `name`.

### Updates (1 tool)

- `check_updates` — detects version drift by hashing tool schemas on each probe and comparing against the last stored hash. Returns `has_changed`, `previous_hash`, `current_hash`, and `changed_at` per server.

### Export (1 tool)

- `export_dashboard` — generates a self-contained single-file HTML dashboard with summary cards, per-server status table with p50/p95 latency, and inline SVG uptime sparklines. Accepts an optional `output_path` to write to disk.

## Manual server registry

In addition to auto-discovery from MCP config files, you can register servers that are not in your Claude Desktop config using the `configure_server` tool. Manually registered servers are written to `~/.mcp/extra-servers.json` (stored alongside the health database) and merged with auto-discovered servers on every probe.

```
Add a server named "my-internal-tool" running with command "node" and args ["/opt/tools/server.js"]
```

To stop monitoring a manually registered server:

```
Remove the server named "my-internal-tool" from monitoring
```

Servers discovered from Claude Desktop's config cannot be removed via `remove_server` — edit your MCP config file directly to remove those.

## Configuration

### `--interval` / `--interval-seconds`

How often to poll each MCP server, in seconds.

Type: `number`
Default: `60`

### `--latency-threshold`

Latency in milliseconds above which a server is marked as degraded.

Type: `number`
Default: `1000`

### `--db` / `--db-path`

Path to the SQLite database file used to store health history.

Type: `string`
Default: `~/.mcp/health.db`

### `--daemon`

Run as a background polling daemon. Health data is collected continuously rather than on-demand.

Type: `boolean`
Default: `false`

### `--startup-grace-seconds`

Grace period in seconds before a newly started server is considered unhealthy.

Type: `number`
Default: `10`

Pass flags via the `args` property in your JSON config:

```json
{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "mcp-server-health-monitor@latest", "--interval=30", "--latency-threshold=500"]
    }
  }
}
```

## Listings

- Listed on the [MCP Registry](https://registry.mcp.so) — search for `mcp-server-health-monitor`.
- Listed on [MCP Market](https://mcpmarket.com) — search for `mcp-server-health-monitor`.

## Verification

Before publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.

**Interactive UI** (opens browser):

```bash
npm run build && npm run inspect
```

**CLI mode** (scripted / CI-friendly):

```bash
# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name health_check_all

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name health_check_all --tool-arg key=value
```

Run before publishing to catch regressions in tool registration and runtime startup.

## Contributing

Probe modules live in `src/probes/`. Each probe must return a `ProbeResult` with `status`, `latencyMs`, and an optional `message`. Keep all probes read-only — never trigger side effects on monitored servers.

```bash
npm install && npm test
```

More