mcp-healthcheck

Programmatic health and liveness probe for MCP (Model Context Protocol) servers.

mcp-healthcheck connects to an MCP server over any supported transport (stdio, Streamable HTTP, or legacy SSE), performs the protocol handshake, enumerates the server's capabilities (tools, resources, prompts), measures latency for each operation, and returns a structured health report. It is designed to run headlessly in automated environments -- Kubernetes liveness/readiness probes, CI pipeline gates, monitoring dashboards -- where interactive debugging tools are not viable.

The package provides both a TypeScript/JavaScript API for programmatic use and a CLI for terminal and shell-script use. The API returns structured HealthReport objects with per-check status, latency, and error details. The CLI prints human-readable or JSON output and exits with conventional codes (0 for healthy, 1 for unhealthy, 2 for configuration errors, 3 for degraded).

The only runtime dependency is @modelcontextprotocol/sdk.

npm install mcp-healthcheck @modelcontextprotocol/sdk

@modelcontextprotocol/sdk is a peer dependency and must be installed alongside this package.

For CLI-only usage without installing locally:

npx mcp-healthcheck --stdio 'node ./server.js'

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'stdio',
    command: 'node',
    args: ['./my-mcp-server.js'],
  },
  timeout: 10_000,
});

console.log(report.status);  // 'healthy' | 'unhealthy' | 'degraded'
console.log(report.totalMs); // 342
console.log(report.checks);  // individual check results

# stdio transport
mcp-healthcheck --stdio 'node ./server.js'

# Streamable HTTP transport
mcp-healthcheck --url https://mcp.example.com/mcp --header 'Authorization:Bearer sk-...'

# Legacy SSE transport
mcp-healthcheck --sse http://localhost:3000/sse

# JSON output for scripting
mcp-healthcheck --stdio 'node ./server.js' --format json

# Quiet mode (exit code only)
mcp-healthcheck --url http://localhost:3000/mcp --quiet

• Three transport types -- stdio (subprocess), Streamable HTTP, and legacy SSE.
• Full MCP lifecycle verification -- transport connectivity, protocol handshake, and capability enumeration (tools, resources, prompts).
• Per-check latency measurement -- high-resolution timing for every check using performance.now().
• Configurable thresholds -- minimum/maximum tool count, minimum resource/prompt count, and maximum latency per check.
• Custom checks -- user-defined async functions that receive the connected MCP Client instance for domain-specific assertions.
• Timeout enforcement -- per-check timeout and overall timeout with automatic cleanup of remaining checks.
• AbortSignal support -- external cancellation via standard AbortSignal interface.
• Auto-skip -- checks for capabilities the server does not declare are automatically skipped with a passing result.
• Structured health reports -- machine-readable HealthReport objects with status, per-check results, summary counts, and server info.
• HTTP handler factory -- mount a health endpoint in Express, Koa, Fastify, or raw http.createServer with a single function call.
• CLI with deterministic exit codes -- 0 (healthy), 1 (unhealthy), 2 (config error), 3 (degraded).
• Environment variable configuration -- all CLI flags have environment variable equivalents for container and CI environments.
• Subprocess cleanup -- stdio transports are always terminated (SIGTERM, then SIGKILL after 5s) to prevent zombie processes.
• Never throws -- checkHealth() always returns a HealthReport, capturing all errors within the report structure.

The primary API. Connects to an MCP server, runs all health checks, and returns a structured report. This function never throws; all errors are captured in the returned report.

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  },
});

if (report.status === 'healthy') {
  console.log(`${report.summary.passed}/${report.summary.total} checks passed in ${report.totalMs}ms.`);
} else {
  for (const check of report.checks.filter(c => !c.passed)) {
    console.error(`FAIL: ${check.name} -- ${check.error?.message}`);
  }
}

Convenience function that runs checkHealth and returns true only when the status is 'healthy'. Returns false for both 'unhealthy' and 'degraded'.

import { isHealthy } from 'mcp-healthcheck';

const healthy = await isHealthy({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
});

if (!healthy) {
  process.exit(1);
}

Creates an HTTP request handler that exposes a health check endpoint. Suitable for mounting in any Node.js HTTP framework or a raw http.createServer.

• GET request: runs checkHealth(options) and responds with 200 OK (healthy or degraded) or 503 Service Unavailable (unhealthy), with Content-Type: application/json and the HealthReport as the response body.
• Any other method: responds with 405 Method Not Allowed.

import http from 'node:http';
import { createHttpHandler } from 'mcp-healthcheck';

const handler = createHttpHandler({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  timeout: 10_000,
});

const server = http.createServer(handler);
server.listen(8080);

Main configuration object passed to checkHealth, isHealthy, and createHttpHandler.

A discriminated union of three transport configurations:

StdioTransportConfig

HttpTransportConfig

SseTransportConfig

type CustomCheckFn = (client: Client) => Promise<CustomCheckResult>;

A user-defined async function that receives the connected MCP Client instance and returns a CustomCheckResult.

The complete health report returned by checkHealth.

type HealthStatus = 'healthy' | 'unhealthy' | 'degraded';

• healthy -- all required checks passed and all thresholds met.
• unhealthy -- one or more required checks failed.
• degraded -- all required checks passed, but optional checks or latency thresholds failed.

Specialized check result details:

Checks run in this fixed order. Each check depends on the previous required check succeeding.

If connect or initialize fails, all subsequent checks are skipped.

If the server does not declare a capability (e.g., resources), the corresponding check is automatically skipped with passed: true.

Timeouts are enforced at two levels:

• Per-check timeout (checkTimeout): each individual check is wrapped in a Promise.race with a timeout. If the check exceeds this, it fails with error code CHECK_TIMEOUT.
• Overall timeout (timeout): a master timer runs for the entire checkHealth() call. If it fires before all checks complete, remaining checks are skipped with error code OVERALL_TIMEOUT.

Both timeout levels use AbortController internally and compose with any caller-provided signal.

checkHealth() never throws. All errors are captured within the returned HealthReport. Failed checks include an error object with a classification code, message, and optional stack trace.

If a required check (connect or initialize) fails, all subsequent checks are skipped and recorded with a message indicating the prior failure. This provides a complete report structure even when early checks fail.

Custom checks run after the standard checks and receive the connected MCP Client instance. Each check can be marked as required (failure makes status 'unhealthy') or optional (failure makes status 'degraded', which is the default).

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  customChecks: [
    {
      name: 'has-search-tool',
      required: true,
      fn: async (client) => {
        const { tools } = await client.listTools();
        const hasSearch = tools.some(t => t.name === 'search');
        return {
          passed: hasSearch,
          message: hasSearch ? 'search tool is registered' : 'search tool is missing',
        };
      },
    },
  ],
});

Custom checks that throw an exception are treated as failures with error code CUSTOM_CHECK_ERROR. Both sync throws and rejected promises are handled.

Pass an AbortSignal to cancel a health check externally:

import { checkHealth } from 'mcp-healthcheck';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);

const report = await checkHealth({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  signal: controller.signal,
});

When aborted, the health check stops immediately and returns an unhealthy report with error code ABORTED.

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'http',
    url: 'https://mcp.example.com/mcp',
    headers: { 'Authorization': 'Bearer sk-...' },
  },
  timeout: 15_000,
  checkTimeout: 5_000,
  thresholds: {
    maxLatencyMs: 2_000,
    minTools: 3,
  },
});

Expose a health check as an HTTP endpoint in any Node.js application:

import http from 'node:http';
import { createHttpHandler } from 'mcp-healthcheck';

const handler = createHttpHandler({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  timeout: 10_000,
});

const server = http.createServer(handler);
server.listen(8080);
// GET http://localhost:8080 -> 200 (healthy/degraded) or 503 (unhealthy)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  template:
    spec:
      containers:
        - name: mcp-server
          image: my-mcp-server:latest
          ports:
            - containerPort: 3000
        - name: healthcheck
          image: node:20-slim
          command: ['sleep', 'infinity']
          livenessProbe:
            exec:
              command:
                - mcp-healthcheck
                - '--url'
                - 'http://localhost:3000/mcp'
                - '--timeout'
                - '5000'
                - '--skip'
                - 'resources'
                - '--skip'
                - 'prompts'
                - '--quiet'
            initialDelaySeconds: 15
            periodSeconds: 30
            timeoutSeconds: 8
            failureThreshold: 3
          readinessProbe:
            exec:
              command:
                - mcp-healthcheck
                - '--url'
                - 'http://localhost:3000/mcp'
                - '--timeout'
                - '5000'
                - '--min-tools'
                - '5'
                - '--quiet'
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 8
            failureThreshold: 1

- name: Wait for MCP server to be healthy
  run: |
    for i in $(seq 1 10); do
      npx mcp-healthcheck \
        --url http://localhost:3000/mcp \
        --timeout 5000 \
        --min-tools 3 \
        --format json \
        && exit 0
      echo "Attempt $i failed, retrying in 2s..."
      sleep 2
    done
    echo "MCP server failed to become healthy"
    exit 1

import { checkHealth } from 'mcp-healthcheck';

const servers = [
  { name: 'search-server', transport: { type: 'http' as const, url: 'https://search.internal/mcp' } },
  { name: 'db-server', transport: { type: 'http' as const, url: 'https://db.internal/mcp' } },
];

const results = await Promise.all(
  servers.map(async (s) => ({
    name: s.name,
    report: await checkHealth({ transport: s.transport, timeout: 10_000 }),
  })),
);

for (const { name, report } of results) {
  console.log(`${name}: ${report.status} (${report.totalMs}ms)`);
}

mcp-healthcheck [options]

Transport (exactly one required):
  --stdio <command>          Spawn an MCP server via stdio transport.
  --url <url>                Connect via Streamable HTTP transport.
  --sse <url>                Connect via legacy SSE transport.

Transport options:
  --header <key:value>       Add an HTTP header (repeatable). For --url and --sse only.
  --cwd <path>               Working directory for --stdio subprocess.
  --env <key=value>          Environment variable for --stdio subprocess (repeatable).

Check options:
  --timeout <ms>             Overall timeout in milliseconds. Default: 30000.
  --check-timeout <ms>       Per-check timeout in milliseconds. Default: 10000.
  --skip <check>             Skip a check (repeatable). Values: tools, resources, prompts.
  --min-tools <n>            Minimum expected tool count.
  --max-tools <n>            Maximum expected tool count.
  --min-resources <n>        Minimum expected resource count.
  --min-prompts <n>          Minimum expected prompt count.
  --max-latency <ms>         Maximum allowed latency per check.

Output options:
  --format <format>          Output format: human, json. Default: human.
  --quiet                    Suppress all output except the exit code.
  --verbose                  Show detailed check information.

Meta:
  --version                  Print version and exit.
  --help                     Print help and exit.

All CLI flags can be set via environment variables. Explicit CLI flags override environment variables.

$ mcp-healthcheck --stdio 'node ./server.js' --min-tools 2

  mcp-healthcheck v0.2.0

  Target: stdio -- node ./server.js
  Status: healthy

  PASS  connect         12ms   stdio transport connected
  PASS  initialize      45ms   protocol v2025-06-18, server: my-server v1.0.0
  PASS  tools           28ms   5 tools: search, create, update, delete, list
  PASS  resources       15ms   2 resources
  PASS  prompts          8ms   1 prompt

  Summary: 5/5 passed in 108ms

This package is written in TypeScript and ships type declarations (dist/index.d.ts). All public types are exported from the main entry point:

import {
  checkHealth,
  isHealthy,
  createHttpHandler,
  // Types
  type HealthCheckOptions,
  type HealthReport,
  type HealthStatus,
  type CheckResult,
  type ConnectCheckResult,
  type InitializeCheckResult,
  type ToolsCheckResult,
  type ResourcesCheckResult,
  type PromptsCheckResult,
  type CustomCheckCheckResult,
  type TransportConfig,
  type StdioTransportConfig,
  type HttpTransportConfig,
  type SseTransportConfig,
  type Thresholds,
  type CustomCheckFn,
  type CustomCheckResult,
} from 'mcp-healthcheck';

Requires TypeScript 5.0 or later. The package compiles to ES2022 with CommonJS modules.

MIT