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

Start Hangar in HTTP mode:
```
mcp-hangar serve --http --port 8000
```

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

Start the monitoring stack:
```
cd monitoring
docker compose up -d
```
Open Grafana at http://localhost:3000 (admin/admin) and check the MCP Hangar dashboard.

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