feat(mcp): reject persisted histogram tiles with unsupported aggFns in query_tile

[pulpdrew]

Why

Histogram and exponential histogram metrics only support count and quantile aggregations in the ClickHouse renderer. The MCP query and dashboard save/patch tools already reject invalid aggFns for these metric kinds at input time (added in #2705 via getMetricSelectIssues). This mirrors the chart-builder UI change that hides those options.

The one remaining MCP gap was clickstack_query_tile: it loads and executes an already-persisted tile without re-validating it. A tile created outside MCP validation — via the REST API, the UI (pre-dating the UI guard), or legacy data — could hold a histogram metric with avg/sum/min/max, and running it surfaced an opaque ClickHouse render error ("<aggFn> is not supported for histograms currently") instead of an actionable message.

What changed

• mcp/tools/dashboards/validation.ts: Added getMetricTileAggFnErrors(tiles), which walks each builder tile's select items and reuses the existing getMetricSelectIssues rules. It inspects only metric select items (those carrying a metricType), maps the persisted periodAggFn: 'delta' back to the isDelta flag, and skips raw SQL / search / heatmap / log / trace items. Returns one human-readable error per offending item.
• mcp/tools/dashboards/queryTile.ts: Before executing a tile, clickstack_query_tile now runs getMetricTileAggFnErrors([tile]) and returns an mcpUserError when the persisted config is invalid, instead of letting the query fail opaquely downstream.

No change to the already-validated surfaces (clickstack_timeseries, clickstack_table, clickstack_save_dashboard, clickstack_patch_dashboard) — those continue to reject invalid histogram aggFns at input time.

Testing

• Unit: packages/api/src/mcp/__tests__/dashboards/validation.test.ts — added coverage for getMetricTileAggFnErrors (histogram/exp-histogram rejection of avg/sum/min/max, acceptance of quantile+level and count, gauge unaffected, non-metric/raw-SQL items ignored, positional labels, multi-item collection). 30/30 passing.
• Integration: packages/api/src/mcp/__tests__/dashboards/queryTile.int.test.ts — added a test that seeds a histogram tile with avg directly into MongoDB (bypassing MCP save validation) and asserts clickstack_query_tile rejects it with "Histogram metrics only support …". 15/15 passing (make dev-int FILE=queryTile).
• yarn tsc --noEmit (packages/api) — clean. yarn lint:fix — no errors.

Linear Issue: HDX-4991

  

[changeset-bot]

🦋 Changeset detected

Latest commit: 548c25d

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Building	Preview	Aug 4, 2026 3:57pm
hyperdx-storybook	Ready	Preview	Aug 4, 2026 3:57pm

[greptile-apps]

Greptile Summary

This PR adds pre-execution validation for persisted metric tiles queried through MCP, returning an actionable user error when histogram or exponential-histogram tiles use unsupported aggregation functions.

• Reuses the existing metric-select validation rules when querying persisted dashboard tiles.
• Maps the external periodAggFn: delta representation back to the validator’s isDelta field.
• Adds unit and integration coverage for supported, unsupported, non-metric, and legacy persisted configurations.
• Includes a patch changeset for the API package.

Confidence Score: 5/5

The PR appears safe to merge, with the new guard consistently validating the persisted external tile representation before execution.

The guard uses the same metric constraints as MCP query and dashboard-write inputs, correctly adapts persisted delta representation, preserves valid metric configurations, and returns invalid configurations through the established user-error path.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/dashboards/validation.ts	Adds persisted builder-tile metric validation using the existing metric-select rules while skipping raw SQL and non-metric configurations.
packages/api/src/mcp/tools/dashboards/queryTile.ts	Runs the new validation before tile execution and returns violations as categorized MCP user errors.
packages/api/src/mcp/tests/dashboards/validation.test.ts	Covers supported and unsupported histogram aggregations, unaffected metric kinds, ignored tile shapes, labels, and multi-item collection.
packages/api/src/mcp/tests/dashboards/queryTile.int.test.ts	Verifies that a directly persisted legacy histogram tile using avg is rejected before renderer execution.
.changeset/mcp-histogram-query-tile-guard.md	Records the user-facing MCP validation behavior as an API patch release.

Sequence Diagram

sequenceDiagram
  participant Client as MCP client
  participant Tool as clickstack_query_tile
  participant Mongo as Dashboard storage
  participant Validator as Metric tile validator
  participant Runner as runConfigTile
  participant CH as ClickHouse

  Client->>Tool: Query persisted tile
  Tool->>Mongo: Load team-scoped dashboard
  Mongo-->>Tool: Persisted tile config
  Tool->>Validator: Validate metric select items
  alt Unsupported histogram aggregation
    Validator-->>Tool: Actionable validation errors
    Tool-->>Client: mcpUserError
  else Valid configuration
    Validator-->>Tool: No errors
    Tool->>Runner: Execute tile
    Runner->>CH: Render and run query
    CH-->>Client: Query result
  end

Loading

_{Reviews (1): Last reviewed commit: "feat(mcp): reject persisted histogram ti..." | Re-trigger Greptile}

[github-actions]

E2E Test Results

✅ All tests passed • 266 passed • 1 skipped • 1104s

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

Tests ran across 4 shards in parallel.

View full report →