feat: Support exponential histograms in MCP

[pulpdrew]

Summary

This PR adds support for Exponential Histogram metrics in the MCP Server's metrics-related tools.

Screenshots or video

How to test

Test locally, with NEXT_PUBLIC_ENABLE_EXPONENTIAL_HISTOGRAMS=true in .env.local. Ask your MCP-connected agent to interact with exponential histogram metrics (you may also need to ask your agent to setup a service to send some exponential histogram metrics to ClickHouse.

This feature toggle will be removed shortly in a followup PR, there isn't a reason to guard these changes with that toggle.

References

• Linear Issue: Closes HDX-4859
• Related PRs:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jul 22, 2026 5:55pm
hyperdx-storybook	Ready	Preview, Comment	Jul 22, 2026 5:55pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 64f2841

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

This PR adds exponential histogram support to MCP metric workflows. The main changes are:

• Adds exponential histograms to metric discovery and pagination.
• Supports quantile and count queries in MCP tools and dashboard tiles.
• Updates validation, prompts, documentation, and usage guidance.
• Adds unit and integration coverage for discovery, querying, and dashboards.

Confidence Score: 5/5

This looks safe to merge.

• The latest fixes align metric validation with the supported renderer operations.
• Discovery, cursor handling, query tools, and dashboard tiles use the same metric-kind value.
• No blocking issue tied to the prior review feedback remains.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/query/schemas.ts	Adds exponential histogram validation and preserves expressionless count aggregations.
packages/api/src/mcp/tools/dashboards/schemas.ts	Allows exponential histogram tiles and defaults value expressions for non-count metric aggregations.
packages/api/src/mcp/tools/sources/metricKinds.ts	Adds exponential histograms to the shared set of queryable metric kinds.
packages/api/src/mcp/tools/sources/listMetrics.ts	Includes exponential histograms in metric discovery and cursor-based pagination.
packages/api/src/mcp/tools/sources/describeMetric.ts	Adds exponential histogram descriptions, aggregation guidance, and query examples.

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into drew/exp-hist-m..." | Re-trigger Greptile}

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 10
• Production lines changed: 131 (+ 329 in test files, excluded from tier calculation)
• Branch: drew/exp-hist-mcp
• Author: pulpdrew

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

E2E Test Results

✅ All tests passed • 242 passed • 1 skipped • 1034s

Status	Count
✅ Passed	242
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

Deep Review

✅ No critical issues found. This PR extends existing 'histogram' handling to 'exponential histogram' across the MCP metric tools, and the additions are consistent and correct. The renderer's translateExponentialHistogram supports both quantile and count, matching exactly the aggregations the MCP validation layer (getMetricSelectIssues) now permits, and MetricsDataType.ExponentialHistogram resolves to the literal 'exponential histogram' so the metricType string flows straight through to renderer dispatch. No code path handles 'histogram' while omitting 'exponential histogram' — every kind-dependent branch either pairs both literals or iterates the shared QUERYABLE_METRIC_KINDS constant.

🟡 P2 — recommended

• packages/api/src/mcp/tools/sources/describeMetric.ts:54 — The new 'exponential histogram' KIND_USAGE entry and the queryExample quantile branch (kind === 'histogram' || kind === 'exponential histogram' at line 647) are new agent-facing guidance with no unit coverage, while the sibling validation paths in schemas.ts, listMetrics.ts, and metricKinds.ts each received exponential-histogram tests.
  • Fix: Add a unit test asserting describeMetric emits the exponential-histogram KIND_USAGE string and a quantile/level queryExample for kind: 'exponential histogram'.

---

Reviewers (4): correctness, testing, maintainability, api-contract.

Review basis / caveat: The sandbox blocked all shell, git, grep/glob, and web access, so the verbatim PR diff could not be retrieved. Findings are derived from reading the source at HEAD and reasoning against base 00eef72 (which already shipped the exponential-histogram SQL renderer). A line-level diff pass was not possible; a re-run in an environment with working git is advisable to confirm no non-exponential-histogram changes were missed.

Testing gaps:

• packages/api/src/mcp/tools/sources/describeMetric.ts and packages/api/src/mcp/tools/sources/describeSource.ts have no unit test files at all (pre-existing structural gap); the exponential-histogram guidance/sampling paths in both are therefore untested.