Health Checks Guide

Name: NitroStack
Author: NitroStack

Overview

In production environments, uptime and operational visibility are critical. NitroStack provides a built-in health checking system that enables container orchestrators (such as Kubernetes, Docker Swarm, and Google Cloud Run) and monitoring agents to assess server vitality.

Each health check reports one of three statuses (HealthCheckResult):

up: The component is operating normally.
degraded: The component is functioning with reduced performance or fallback capacity.
down: The component is unavailable or failing critical requirements.

All registered health checks are automatically aggregated and exposed through a standard MCP resource: health://checks.

Defining a Health Check

Health checks are defined as injectable classes implementing HealthCheckInterface and decorated with @HealthCheck:

Typescript
// src/modules/health/system-health.check.ts
import { HealthCheck, HealthCheckInterface, HealthCheckResult, Injectable } from '@nitrostack/core';

@HealthCheck({ name: 'system' })
@Injectable()
export class SystemHealthCheck implements HealthCheckInterface {
  async check(): Promise<HealthCheckResult> {
    const memory = process.memoryUsage();
    const heapUsedMb = Math.round(memory.heapUsed / 1024 / 1024);
    const uptimeSeconds = Math.round(process.uptime());

    // Flag degraded if heap exceeds 500MB
    const status = heapUsedMb > 500 ? 'degraded' : 'up';

    return {
      status,
      message: status === 'up' ? 'System healthy' : 'High memory consumption',
      details: {
        uptimeSeconds,
        heapUsedMb,
        rssMb: Math.round(memory.rss / 1024 / 1024),
        nodeVersion: process.version,
      },
    };
  }
}

Service & Database Health Check Example

Here is an example verifying database connectivity and library inventory health:

Typescript
// src/modules/library/library-health.check.ts
import { HealthCheck, HealthCheckInterface, HealthCheckResult, Injectable } from '@nitrostack/core';
import { LibraryService } from './library.service.js';

@HealthCheck({ name: 'library_repository' })
@Injectable()
export class LibraryRepositoryHealthCheck implements HealthCheckInterface {
  constructor(private libraryService: LibraryService) {}

  async check(): Promise<HealthCheckResult> {
    try {
      const stats = await this.libraryService.getStats();

      return {
        status: 'up',
        message: 'Database connection active',
        details: {
          totalBooks: stats.totalBooks,
          availableCopies: stats.availableCopies,
          latencyMs: stats.queryLatencyMs,
        },
      };
    } catch (err) {
      return {
        status: 'down',
        message: 'Database query failed',
        details: {
          error: err instanceof Error ? err.message : 'Unknown database error',
        },
      };
    }
  }
}

Registering Health Checks

Typescript
// src/modules/health/health.module.ts
import { Module } from '@nitrostack/core';
import { SystemHealthCheck } from './system-health.check.js';
import { LibraryRepositoryHealthCheck } from './library-health.check.js';

@Module({
  name: 'health',
  description: 'Server health and liveness monitoring',
  providers: [SystemHealthCheck, LibraryRepositoryHealthCheck],
  exports: [SystemHealthCheck, LibraryRepositoryHealthCheck],
})
export class HealthModule {}

Import this module into your root AppModule:

Typescript
// src/app.module.ts
import { McpApp, Module } from '@nitrostack/core';
import { HealthModule } from './modules/health/health.module.js';

@McpApp({ module: AppModule })
@Module({
  imports: [HealthModule],
})
export class AppModule {}

The `health://checks` Resource

When health checks are registered in your application modules, NitroStack automatically registers and exposes an aggregated MCP resource at health://checks. Clients or monitoring scripts reading this resource receive a unified JSON payload:

JSON
{
  "checks": [
    {
      "name": "system",
      "status": "up",
      "message": "System healthy",
      "details": {
        "uptimeSeconds": 1420,
        "heapUsedMb": 78,
        "rssMb": 112,
        "nodeVersion": "v20.18.0"
      },
      "timestamp": 1727045100000
    },
    {
      "name": "library_repository",
      "status": "up",
      "message": "Database connection active",
      "details": {
        "totalBooks": 240,
        "availableCopies": 510,
        "latencyMs": 4
      },
      "timestamp": 1727045100000
    }
  ],
  "count": 2,
  "timestamp": "2026-09-22T16:45:00.000Z"
}

The @nitrostack/core package also exports programmatic health check utilities:

getAllHealthChecks(): Returns a Record<string, HealthCheckResult>.
getHealthCheck(name: string): Returns the result of a specific health check.
getOverallHealth(): Returns { status: 'healthy' | 'unhealthy' | 'degraded', checks }.

Container & Cloud Orchestration

Kubernetes Probes

Configure liveness and readiness probes in your deployment manifest:

Yaml
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 15
readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 2
  periodSeconds: 10

Docker HEALTHCHECK

In your Dockerfile:

Dockerfile

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:8080/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1); })"

Best Practices

Keep Checks Non-Destructive: Health checks should be idempotent and read-only.
Implement Sensible Timeouts: Ensure checks timeout within 2–5 seconds so orchestrators do not hang.
Decouple Critical from Non-Critical: Mark third-party external integrations as 'degraded' rather than 'down' if the core MCP server can continue servicing local queries.
Automate Alerting: Wire Prometheus, Datadog, or Cloud Monitoring to scrape the aggregated health metrics periodically.

Server Concepts — Server lifecycle and bootstrapping
Resources Guide — Exposing contextual resources to AI models
Production Deployment — Preparing your MCP server for production