Skip to content

07 -- Observability: Metrics

Prerequisite: 01 -- HTTP Gateway You will need: Running Hangar in HTTP mode, Docker for monitoring stack Time: 10 minutes Adds: Prometheus metrics and Grafana dashboards

The Problem

You have MCP servers running. You don't know how many tool calls they handle, how long calls take, or whether health checks are passing. When something breaks at 3 AM, you need data, not guesses.

The Config

# config.yaml -- Recipe 07: Observability Metrics
mcp_servers:
  my-mcp:
    mode: remote
    endpoint: "http://localhost:8080"
    health_check_interval_s: 10
    max_consecutive_failures: 3

No config changes needed -- metrics are always available at /metrics on the HTTP server.

Try It

  1. Start Hangar in HTTP mode:
mcp-hangar serve --http --port 8000
  1. Check Prometheus metrics are exposed:
curl -s http://localhost:8000/metrics | head -20

# HELP mcp_hangar_tool_calls_total Total tool invocations
# TYPE mcp_hangar_tool_calls_total counter
mcp_hangar_tool_calls_total{mcp_server="my-mcp",tool="my-tool"} 0
# HELP mcp_hangar_mcp_server_state Current mcp_server state
# TYPE mcp_hangar_mcp_server_state gauge
  1. Start the monitoring stack:
cd monitoring
docker compose up -d

  1. Open Grafana at http://localhost:3000 (admin/admin) and check the MCP Hangar dashboard.

  2. Make some tool calls and watch the metrics update in real time:

curl -X POST http://localhost:8000/api/mcp_servers/my-mcp/start

What Just Happened

Hangar exposes Prometheus-format metrics at /metrics. The monitoring stack in monitoring/ includes pre-configured Prometheus scraping and Grafana dashboards. Key metrics:

Metric Type What it tells you
mcp_hangar_tool_calls_total Counter Total tool invocations per MCP server/tool
mcp_hangar_tool_call_duration_seconds Histogram Latency distribution per MCP server/tool
mcp_hangar_mcp_server_state Gauge Current state per MCP server (0=cold, 1=initializing, 2=ready, 3=degraded, 4=dead)
mcp_hangar_mcp_server_cold_start_seconds Histogram Cold start latency per MCP server
mcp_hangar_health_checks_total Counter Health check results per MCP server
mcp_hangar_circuit_breaker_state Gauge Circuit breaker state per MCP server

Key Config Reference

No new config keys. Metrics are always available in HTTP mode.

Endpoint Description
/metrics Prometheus text format

What's Next

Metrics tell you what happened. Traces tell you why.

--> 08 -- Observability: Langfuse