Skip to content

Health Check API Reference ​

The 1MCP Agent provides comprehensive health check endpoints for monitoring system status, server connectivity, and operational metrics.

Overview ​

Health check endpoints are designed for:

  • Load Balancers: HAProxy, nginx, AWS ALB
  • Container Orchestration: Kubernetes, Docker Swarm
  • CI/CD Pipelines: Deployment validation
  • Manual Debugging: System status inspection

Security Configuration ​

The health endpoints include configurable security features to control information exposure:

Detail Levels:

  • full: Complete system information with error sanitization
  • basic: Limited system details, sanitized errors, server status
  • minimal (default): Only essential status information for /health; diagnostic routes have separate disclosure limits

Configuration:

bash
# CLI option (default is minimal)
1mcp --config mcp.json --health-info-level basic

# Environment variable
export ONE_MCP_HEALTH_INFO_LEVEL=basic
1mcp --config mcp.json

Sanitization Features:

  • Automatic error message sanitization for /health and serialized supervision fields
  • Credential pattern removal (user:password@, tokens, keys)
  • URL and file path redaction
  • IP address anonymization

The detail policy applies to /health and serialized backendSupervision fields. It does not redact all loading diagnostics in /health/mcp or /health/mcp/:serverName: backend errors and OAuth authorization URLs can remain visible even at minimal. Health routes are not protected by MCP authentication. Restrict diagnostic routes at your network or reverse proxy rather than relying on the detail level alone.

Endpoints ​

GET /health ​

Description: Complete health status with detailed system metrics and server information.

Authentication: None required

Response Codes:

  • 200 - Healthy or degraded but functional
  • 503 - Unhealthy, critical issues
  • 500 - Internal server error

Response Headers:

http
Content-Type: application/json
Cache-Control: no-cache, no-store, must-revalidate
X-Health-Status: healthy|degraded|unhealthy
X-Service-Version: 0.15.0
X-Uptime-Seconds: 3600

Response Schema:

json
{
  "status": "healthy|degraded|unhealthy",
  "timestamp": "2025-01-30T12:00:00.000Z",
  "version": "0.15.0",
  "system": {
    "uptime": 3600,
    "memory": {
      "used": 50.5,
      "total": 100.0,
      "percentage": 50.5
    },
    "process": {
      "pid": 12345,
      "nodeVersion": "v20.0.0",
      "platform": "linux",
      "arch": "x64"
    }
  },
  "servers": {
    "total": 3,
    "healthy": 2,
    "unhealthy": 1,
    "details": [
      {
        "name": "filesystem-server",
        "status": "connected|error|disconnected|awaiting_oauth",
        "healthy": true,
        "lastConnected": "2025-01-30T11:30:00.000Z",
        "lastError": "Connection timeout",
        "tags": ["filesystem", "local"]
      }
    ]
  },
  "configuration": {
    "loaded": true,
    "serverCount": 3,
    "enabledCount": 2,
    "disabledCount": 1,
    "authEnabled": true,
    "transport": "http"
  }
}

Field Descriptions:

  • status: Overall health status

    • healthy - All systems operational
    • degraded - Some issues but still functional
    • unhealthy - Critical issues affecting functionality
  • system.uptime: Server uptime in seconds

  • system.memory.used: Heap memory used in MB

  • system.memory.total: Total heap memory in MB

  • system.memory.percentage: Memory usage percentage

  • servers.details[].status: Individual server status

    • connected - Server is connected and operational
    • error - Server has connection or runtime errors
    • disconnected - Server is not connected
    • awaiting_oauth - Server requires OAuth authentication

GET /health/live ​

Description: Simple liveness probe for basic availability checking.

Authentication: None required

Response Codes:

  • 200 - Server is running (always returns 200 if reachable)

Response Schema:

json
{
  "status": "alive",
  "timestamp": "2025-01-30T12:00:00.000Z"
}

Use Cases:

  • Kubernetes liveness probes
  • Load balancer basic health checks
  • Service discovery health checks

GET /health/ready ​

Session admission is reported separately as sessionAdmission.available. At the existing subscription-owner safety cap, fresh Streamable HTTP initialization returns HTTP 503 and readiness returns 503 with not_ready; existing sessions remain usable. Deleting a session or reclaiming an idle session restores admission automatically. Backend health and supervision keep their existing meanings.

Description: Configuration and supervised-backend readiness probe. It returns 503 while any supervised stdio backend is restarting or in a crash loop. It does not wait for backend loading or a server-count threshold; use /health/mcp to inspect backend loading progress.

Authentication: None required

Response Codes:

  • 200 - Service is ready (configuration loaded)
  • 503 - Service is not ready

Response Schema (minimal detail):

json
{
  "status": "ready|not_ready",
  "sessionAdmission": { "available": true },
  "timestamp": "2025-01-30T12:00:00.000Z",
  "configuration": {
    "loaded": true,
    "serverCount": 3,
    "enabledCount": 2,
    "disabledCount": 1,
    "authEnabled": true,
    "transport": "http"
  },
  "backendSupervision": {
    "total": 2,
    "connected": 2,
    "restarting": 0,
    "crashLoop": 0,
    "stopped": 0
  }
}

Readiness returns 503 while any supervised stdio backend is restarting or in crash-loop. The backendSupervision shape follows the configured health detail level: aggregate counts for minimal, sanitized per-backend facts without PIDs for basic, and detailed sanitized facts for full.

Use Cases:

  • Kubernetes readiness probes
  • Load balancer ready checks
  • Deployment validation

GET /health/mcp and GET /health/mcp/:serverName ​

These endpoints report MCP loading progress and supervised backend state when the loading manager is available. The collection endpoint includes loading summaries plus backendSupervision; the server-specific endpoint returns 503 for a supervised backend that is restarting or in crash-loop. Supervision output follows the same minimal, basic, and full disclosure policy described above.

Health Status Logic ​

Overall Status Determination ​

The overall health status is determined by:

  1. Configuration Status: Must be loaded for healthy or degraded
  2. Server Health Ratio:
    • All servers healthy → healthy
    • No servers configured → degraded
    • 50% servers healthy → degraded

    • ≤50% servers healthy → unhealthy

Server Health Classification ​

Individual servers are considered healthy if:

  • Status is connected
  • No recent critical errors
  • Responding to health checks

Rate Limiting ​

Health endpoints have relaxed rate limiting:

  • Window: 5 minutes
  • Limit: 200 requests per IP
  • Headers: Standard rate limit headers included

Monitoring Integration Examples ​

Kubernetes Health Probes ​

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: 1mcp-agent
spec:
  template:
    spec:
      containers:
        - name: 1mcp
          image: ghcr.io/1mcp-app/agent:latest
          ports:
            - containerPort: 3050
          livenessProbe:
            httpGet:
              path: /health/live
              port: 3050
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 3050
            initialDelaySeconds: 5
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3

Docker Compose Health Check ​

yaml
version: '3.8'
services:
  1mcp:
    image: ghcr.io/1mcp-app/agent:latest
    ports:
      - '3050:3050'
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3050/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

HAProxy Backend Health Check ​

backend 1mcp_servers
    balance roundrobin
    option httpchk GET /health/ready
    http-check expect status 200
    server 1mcp-1 1mcp-1:3050 check inter 30s
    server 1mcp-2 1mcp-2:3050 check inter 30s

Script-Based Monitoring ​

bash
#!/bin/bash
# Simple health check script

HEALTH_URL="http://localhost:3050/health"
RESPONSE=$(curl -s -w "%{http_code}" -o /tmp/health.json "$HEALTH_URL")
HTTP_CODE="${RESPONSE: -3}"

if [ "$HTTP_CODE" -eq 200 ]; then
    STATUS=$(jq -r '.status' /tmp/health.json)
    UNHEALTHY=$(jq -r '.servers.unhealthy' /tmp/health.json)

    echo "1MCP Health: $STATUS (Unhealthy servers: $UNHEALTHY)"

    if [ "$STATUS" = "unhealthy" ]; then
        exit 1
    fi
else
    echo "1MCP Health Check Failed: HTTP $HTTP_CODE"
    exit 1
fi

Error Responses ​

Service Unavailable (503) ​

json
{
  "status": "unhealthy",
  "timestamp": "2025-01-30T12:00:00.000Z",
  "version": "0.15.0",
  "system": {/* system info */},
  "servers": {
    "total": 3,
    "healthy": 0,
    "unhealthy": 3,
    "details": [/* server details */]
  },
  "configuration": {
    "loaded": false,
    "serverCount": 0,
    "enabledCount": 0,
    "disabledCount": 0,
    "authEnabled": false,
    "transport": "http"
  }
}

Internal Server Error (500) ​

json
{
  "status": "unhealthy",
  "timestamp": "2025-01-30T12:00:00.000Z",
  "error": "Health check failed",
  "message": "Configuration service unavailable"
}

Security Considerations ​

Production Deployment ​

Network-Level Protection (Recommended):

  • Restrict health endpoints to monitoring networks only
  • Use firewall rules to limit access to trusted IPs
  • Consider VPN or private network access for detailed endpoints

Information Exposure Control:

  • Use basic or minimal for /health, and restrict access to diagnostic /health/mcp routes
  • full detail level recommended only for private networks
  • /health and serialized supervision fields sanitize errors; raw loading diagnostics require separate access restrictions

Example Security Configuration:

bash
# Development environment
1mcp --config mcp.json --health-info-level full

# Staging environment
1mcp --config mcp.json --health-info-level basic

# Production: minimal /health detail; restrict diagnostic routes separately
1mcp --config mcp.json

Detail Level Impact ​

This table covers /health and serialized supervision output, not the raw loading diagnostics in /health/mcp.

LevelSystem InfoServer DetailsBackend SupervisionError MessagesUse Case
fullCompleteComplete + sanitizedDetailed, including PIDsSanitizedInternal monitoring
basicLimitedStatus + sanitizedPer-backend, no PIDsSanitizedRestricted monitoring
minimalBasic onlyCounts onlyAggregate state counts onlyNonePublic/Load balancer

Best Practices ​

Monitoring Setup ​

  1. Use Multiple Endpoints: Combine /health, /health/live, and /health/ready for comprehensive monitoring
  2. Set Appropriate Timeouts: Health checks should complete within 5-10 seconds
  3. Configure Retry Logic: Allow 2-3 retries with exponential backoff
  4. Monitor Trends: Track health status changes over time
  5. Security-First: Choose appropriate detail level for your network exposure

Development Testing ​

bash
# Test all health endpoints
curl -v http://localhost:3050/health
curl -v http://localhost:3050/health/live
curl -v http://localhost:3050/health/ready

# Check response headers
curl -I http://localhost:3050/health

# Monitor health status
watch -n 5 'curl -s http://localhost:3050/health | jq ".status, .servers.healthy, .servers.unhealthy"'

Released under the Apache 2.0 License.