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, no sensitive details

Configuration:

# CLI option (default is minimal)
npx -y @1mcp/agent --config mcp.json --health-info-level basic

# Environment variable
export ONE_MCP_HEALTH_INFO_LEVEL=basic
npx -y @1mcp/agent --config mcp.json

Sanitization Features:

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

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:

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:

{
  "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:

{
  "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

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):

{
  "status": "ready|not_ready",
  "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

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

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

#!/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)

{
  "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)

{
  "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 detail levels for public-facing deployments
• full detail level recommended only for private networks
• Error sanitization is always enabled to prevent credential leakage

Example Security Configuration:

# Development environment
npx -y @1mcp/agent --config mcp.json --health-info-level full

# Staging environment
npx -y @1mcp/agent --config mcp.json --health-info-level basic

# Production environment (default minimal level is secure)
npx -y @1mcp/agent --config mcp.json

Detail Level Impact

Level	System Info	Server Details	Backend Supervision	Error Messages	Use Case
full	Complete	Complete + sanitized	Detailed, including PIDs	Sanitized	Internal monitoring
basic	Limited	Status + sanitized	Per-backend, no PIDs	Sanitized	Restricted monitoring
minimal	Basic only	Counts only	Aggregate state counts only	None	Public/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

# 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"'