ClickHouse (ClickStack) Integration

Overview

ClickStack - the ClickHouse observability stack - and Hud operate at two different layers, which is exactly why they work well together:

• ClickStack uses OpenTelemetry data to give you broad visibility across distributed systems and infrastructure. It localizes an issue to a service, deployment, and endpoint, at scale.
• Hud operates at the code layer. Its Runtime Code Sensor captures function-level metrics and deep forensic context, connecting production behavior back to the source code and the change behind it.

Instrumenting every function with OpenTelemetry is impractical. Once ClickStack narrows the search space, Hud provides the fine-grained context needed to understand exactly what happened inside the code.

The two datasets stay correlated through a deliberately boring mechanism: trace IDs. Hud's forensics are enriched with the same OpenTelemetry trace IDs that ClickStack stores with its traces and logs. That single shared key is what lets an agent hop between the two systems.

How it works

Both Hud and ClickStack expose their data through an MCP server. When you connect both MCP servers to the same coding agent (Claude Code, Cursor, and others), the agent can move between the two systems on its own, using the OpenTelemetry trace ID as the join key.

  ClickStack MCP                                              Hud MCP
  ─────────────                                              ───────
  logs / traces / metrics                                    function metrics / forensics
  service · deployment · endpoint                            code-level root cause

                    ◀───────────────── otel_trace_id ─────────────────
                    ──────── service / deployment / endpoint ────────▶

• Hud → ClickStack: Hud flags a failing or regressed function. Its forensics contain the exact otel_trace_id of the affected flows. The agent hands that trace ID to the ClickStack MCP to pull the corresponding logs and spans, no scanning low-signal data or narrowing by timeframe by hand.
• ClickStack → Hud: ClickStack localizes an issue to a service, deployment, and endpoint. The agent hands that scope to the Hud MCP to get the function-level metrics and forensic root cause behind it.

Because the correlation runs inside the agent, there is no data pipeline to build and nothing to sync; the trace ID is already present on both sides.

Setup

1. Connect the Hud MCP server

Follow Start Using Hud MCP Server to add Hud to your agent (via the IDE extension), or use the Hud Remote MCP Server for CI and agentic workflows.

2. Connect the ClickStack MCP server

ClickStack ships its own MCP server (Streamable HTTP + Bearer auth). For Claude Code:

claude mcp add --transport http clickstack <your-hyperdx-url>/api/mcp \
  --header "Authorization: Bearer <your-personal-access-key>"

See the ClickStack MCP server docs for other clients and for how to generate a personal access key.

3. Make sure trace context is propagated

Hud reads trace IDs from the incoming request headers of each flow. For correlation to work, your services must propagate OpenTelemetry (or another supported) trace context, which they already do if ClickStack is collecting your traces.

Where the trace ID lives

Hud records the trace context present on each request in the forensics, under observability_identifiers. The field that matches ClickStack is otel_trace_id — the OpenTelemetry trace ID, captured from the W3C traceparent header. An agent reads it straight off the forensic record and uses it to query ClickStack.

Example: root-cause across both datasets

A prompt you can hand an agent that has both MCP servers connected:

Find the root cause of the checkout.processPayment regression: get the forensics and
otel_trace_id from Hud, correlate on that trace ID to pull ClickStack's spans and logs, and
explain what broke from both.

The agent works both datasets against each other:

• Hud MCP gives the code-level picture — which function regressed, its forensics, the exact parameters and exception on the failing flows, and the otel_trace_id of each.
• ClickStack MCP, queried with those trace IDs, gives the surrounding request — upstream and downstream spans, logs, and the deployment and infrastructure context around the same requests.

Reasoning over both, the agent explains what changed in the code and how it played out across the system — e.g. a new parameter in processPayment triggering a slow downstream call visible only in the ClickStack spans — instead of guessing from either layer alone.