Gnosari Documentation

Appearance

Health Check ​

Health check endpoint for monitoring Gnosari MCP server status and uptime.

Use cases:

  • Integration into monitoring systems (Datadog, New Relic, etc.)
  • Kubernetes liveness/readiness probes
  • Simple uptime checks
  • Verify server connectivity before operations

Key features:

  • No authentication required
  • Fast, lightweight response
  • Returns server version and API URL

gnosari_health ​

Health check for monitoring Gnosari MCP server status.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Parameters ​

None. This endpoint requires no parameters.

Returns ​

typescript
{
  status: "healthy",
  server: "gnosari-mcp",
  version: string,
  api_url: string
}

Response fields:

  • status: Always "healthy" if server is responding
  • server: Server name identifier
  • version: Current MCP server version
  • api_url: Backend API URL the server connects to

Examples ​

Basic health check:

python
health = gnosari_health()
print(f"Status: {health['status']}")
print(f"Version: {health['version']}")
print(f"API: {health['api_url']}")

Monitoring integration:

python
def check_server_health():
    try:
        health = gnosari_health()
        if health["status"] == "healthy":
            return True
        else:
            return False
    except Exception as e:
        print(f"Health check failed: {e}")
        return False

# Use in monitoring loop
import time

while True:
    if not check_server_health():
        print("ALERT: Server unhealthy!")
    time.sleep(60)  # Check every minute

Pre-flight check before operations:

python
# Verify connectivity before heavy operations
health = gnosari_health()
if health["status"] == "healthy":
    print(f"Server ready (version {health['version']})")

    # Proceed with operations
    agents = gnosari_search(query="", entity="agents")
    # ...
else:
    print("Server not available. Aborting.")

Kubernetes readiness probe:

yaml
readinessProbe:
  exec:
    command:
    - /bin/sh
    - -c
    - |
      python -c "
      from tools.utility import gnosari_health
      health = gnosari_health()
      exit(0 if health['status'] == 'healthy' else 1)
      "
  initialDelaySeconds: 5
  periodSeconds: 10

HTTP Endpoint ​

The health check is also available as an HTTP endpoint for non-MCP clients:

Endpoint: GET /health

Response:

json
{
  "status": "healthy",
  "server": "gnosari-mcp",
  "version": "0.3.0",
  "api_url": "https://api.gnosari.com"
}

Use cases:

  • Kubernetes HTTP probes
  • Load balancer health checks
  • External monitoring services

Example with curl:

bash
curl http://localhost:8080/health

Best Practices ​

  1. No authentication - Health check doesn't require credentials for monitoring simplicity
  2. Fast response - Designed to return quickly for monitoring systems
  3. Use for uptime checks - Perfect for simple "is it alive?" checks
  4. Check before batch operations - Verify connectivity before starting long-running tasks
  5. Monitor API URL - Track if server is connecting to expected backend

Common Patterns ​

Retry Logic with Health Check ​

python
import time

def call_with_retry(operation, max_retries=3):
    for attempt in range(max_retries):
        # Check health first
        health = gnosari_health()
        if health["status"] != "healthy":
            print(f"Server unhealthy, attempt {attempt + 1}/{max_retries}")
            time.sleep(2)
            continue

        # Attempt operation
        try:
            return operation()
        except Exception as e:
            print(f"Operation failed: {e}")
            time.sleep(2)

    raise Exception("Max retries exceeded")

# Usage
agents = call_with_retry(lambda: gnosari_search(query="", entity="agents"))

Version Tracking ​

python
# Track server version for compatibility
health = gnosari_health()
server_version = health["version"]

REQUIRED_VERSION = "0.3.0"
if server_version < REQUIRED_VERSION:
    print(f"Warning: Server version {server_version} is below required {REQUIRED_VERSION}")

Environment Verification ​

python
# Verify connecting to correct environment
health = gnosari_health()
api_url = health["api_url"]

EXPECTED_API = "https://api.gnosari.com"
if api_url != EXPECTED_API:
    print(f"WARNING: Connected to {api_url}, expected {EXPECTED_API}")

Response Status ​

The health check always returns "healthy" if the server is running and can respond. If the server is down or unreachable, the call will fail with an exception rather than returning an unhealthy status.

This means:

  • Response received = server is healthy
  • Exception/timeout = server is unhealthy

Example:

python
try:
    health = gnosari_health()
    # If we get here, server is healthy
    print("✓ Server healthy")
except Exception:
    # Connection failed = server unhealthy
    print("✗ Server unreachable")

Next Steps ​