Docs

Quickstart

The Helm chart bundles a single-replica Redis by default, so a fresh install is self-contained. image.registry is the only required value.

# Build + push all three images (versioned + latest), then helm upgrade --install:
REGISTRY=<your-registry> ./deploy.sh

# Or with helm directly against pre-built images:
helm upgrade --install graph helm/graph \
  --namespace default --create-namespace \
  --set image.registry=<your-registry>

Already have Redis? Point at it with --set redis.internal.enabled=false:

helm ... --set redis.internal.enabled=false \
  --set redis.host=my-redis --set redis.password=s3cret

kubectl create secret generic redis-creds \
  --from-literal=REDIS_HOST=my-redis \
  --from-literal=REDIS_PASSWORD=s3cret

helm ... --set redis.internal.enabled=false \
  --set redis.existingSecret=redis-creds

Helm knobs

The values you'll reach for most often. See the chart README for the complete list.

OTel Collector setup

graph-otel consumes trace spans directly — no spanmetrics connector or metrics pipeline required. Fan the spans your apps already emit to graph-otel alongside your existing trace backend. The k8sattributes preset adds the k8s.* attributes graph-otel needs to attach relationships to the right container.

# otel-collector-values.yaml
mode: deployment

image:
  repository: ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib

# Adds the k8sattributes processor (+ RBAC) so spans carry
# k8s.namespace.name / k8s.pod.name / k8s.container.name.
presets:
  kubernetesAttributes:
    enabled: true

config:
  exporters:
    # graph-otel reconstructs whole traces in memory (for flows), so every
    # span of a trace must reach the SAME replica. The loadbalancing exporter
    # shards by trace id across the graph-otel pods, discovered via the
    # headless Service (returns one A record per pod).
    loadbalancing:
      routing_key: traceID
      resolver:
        dns:
          hostname: graph-otel-otlp-headless.default.svc.cluster.local
          port: 4317
      protocol:
        otlp:
          tls:
            insecure: true

  service:
    pipelines:
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [loadbalancing]

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm upgrade --install otel-collector open-telemetry/opentelemetry-collector \
  -f otel-collector-values.yaml

Already exporting traces? Add the loadbalancing exporter alongside your existing one in the traces pipeline (exporters: [your-backend, loadbalancing]). The trace-id sharding keeps each trace whole across graph-otel replicas, which its flow assembly requires.

MCP / Claude Code

The same graph-read binary runs an MCP server in mcp mode. It's a thin REST client of the query API — set GRAPH_BASE_URL to point it at the API. Expose the query API with the chart's built-in Ingress so the MCP server can run anywhere:

helm ... \
  --set graphRead.ingress.enabled=true \
  --set graphRead.ingress.className=nginx \
  --set graphRead.ingress.hosts[0].host=graph.example.com \
  --set graphRead.ingress.hosts[0].paths[0].path=/ \
  --set graphRead.ingress.hosts[0].paths[0].pathType=Prefix

The query API has no authentication and includes the destructive POST /prune — add auth at the ingress (basic-auth / oauth2-proxy annotations) or restrict source IPs before exposing it.

Then register it with Claude Code / Claude Desktop, pointing GRAPH_BASE_URL at the ingress host:

{
  "mcpServers": {
    "graph": {
      "command": "graph-read",
      "args": ["mcp"],
      "env": { "GRAPH_BASE_URL": "https://graph.example.com" }
    }
  }
}

The six tools

• search Find entities by keyword across IDs, names, metadata values, and edge actions.
• get_entity Full detail for one entity by exact ID: kind, metadata, and all outbound edges.
• list_entities Enumerate every entity of a given kind.
• get_subgraph Every entity reachable from a root via BFS (blast radius / call neighborhood).
• list_flows Distinct trace flows — request shapes collapsed from many traces.
• get_flow The full canonical structure of one trace flow by root hash.

REST API

Served by graph-read on :8080. The MCP tools mirror these endpoints.

The query API has no authentication and includes the destructive POST /prune. Put auth in front (ingress basic-auth / oauth2-proxy) or restrict source IPs before exposing it.

Graph schema

<prefix>:entity:<id>            HASH  id, kind, name, last_seen_at_ms
<prefix>:entity:<id>:metadata   HASH  arbitrary string key/values
<prefix>:entity:<id>:edges      SET   JSON-encoded Edge objects
<prefix>:by_kind:<kind>         SET   entity IDs of the given kind
<prefix>:ids                    SET   all entity IDs