MCP: validated product analytics agent feedback (dashboards, insights, SQL) #108309

Validated backlog of the product analytics issues that agents reported through the MCP agent-feedback channel over the last 30 days. Each item was checked against master by reading the code (not reproduced live). Items are ranked by impact: wrong data or a blocked task first.

Each item is scoped so that an agent can pick it up on its own. Please comment on the issue when you take an item, and link your PR.

Why: a lot of the agent feedback is valid, but some of it is stale or comes from agent mistakes. This issue lists only what the code confirms, with a suggested fix for each.

1. Cursor: insight-create and dashboard-create are not available

Status: partly true · Impact: high, because the user cannot save the funnel or dashboard they asked for

• Both tools are enabled: true, have no feature flag, and require insight:write / dashboard:write.
• Cursor runs in tools mode (TOOLS_MODE_CLIENT_NAME_FRAGMENTS = ['cursor'] in services/mcp/src/lib/client-detection.ts). The Cursor OAuth grant does not include those write scopes, so getToolsFromContext filters the tools out. Scope-gated hints (getScopeGatedTools) are only built in single-exec mode, so Cursor gets no hint that explains why the tools are missing.

Suggested fix: (a) decide whether the Cursor OAuth client should request insight:write and dashboard:write, and add them if so. (b) In tools mode, give missing-scope guidance too, for example in the server instructions, so that the agent tells the user to reconnect with the scope.

2. insight-update / insight-create remove chart settings without an error

Status: confirmed · Impact: high, because read → update → write loses settings and the save still reports success

• AssistantDataVisualizationChartSettings (generated in services/mcp/src/tools/generated/product_analytics.ts, source frontend/src/queries/schema/schema-assistant-queries.ts) is a strict subset of ChartSettings (schema-general.ts). Zod removes unknown keys without an error.
• Fields that are lost: yAxisAtZero, showXAxisTicks, showXAxisBorder, showYAxisBorder, showAnnotations, legendPosition, heatmap, pie, scatter, metric, resultCustomizations, chartStyle, and tableSettings.conditionalFormatting.

Suggested fix: either make the assistant chart and table settings schemas pass unknown keys through (.passthrough() / catchall), or widen them to match ChartSettings. Also consider a server-side merge of chartSettings on PATCH when the caller omits keys. Add a test that shows a read-modify-write keeps every field.

3. dashboard-update cannot set tile color, and dashboard-get hides breakdown_colors

Status: confirmed (the layouts part is stale) · Impact: medium

• DashboardPatchTileOpenApiSerializer (products/dashboards/backend/widget_specs/openapi.py) documents only id, layouts and widget, so the generated MCP schema has no color. The backend already accepts it (TILE_DISPLAY_FIELDS in products/dashboards/backend/api/dashboard.py).
• products/dashboards/mcp/tools.yaml excludes breakdown_colors, data_color_theme_id and tiles.*.color from the dashboard-create, dashboard-get and dashboard-update responses. dashboard-update still accepts breakdown_colors, so an agent can write colors that it cannot read back.
• Tile layouts on dashboard-update works on master. Those reports are stale.

Suggested fix: add color (with help text that lists the allowed names) to DashboardPatchTileOpenApiSerializer, then regenerate (hogli build:openapi). Remove breakdown_colors and tiles.*.color from the response exclude lists, at minimum for dashboard-get.

4. Annotations cannot be attached to a specific insight or dashboard over MCP

Status: confirmed · Impact: medium

• annotation-create (products/annotations/mcp/tools.yaml) exposes scope with dashboard_item and dashboard values, but include_params omits dashboard_item and dashboard_id. The generated annotations-partial-update also omits them. The resulting scope has no target.

Suggested fix: add dashboard_item and dashboard_id to both tools. Require the matching id when scope is dashboard_item or dashboard, either with a serializer validation in products/annotations/backend/api/annotation.py or in the tool description. Update the description so that it names the insight or dashboard use case.

5. execute-sql returns an "internal error" or 500 when {filters.dateRange.*} is outside a comparison

Status: confirmed, but the cause is not numbers() · Impact: medium

• In posthog/hogql/filters.py (visit_placeholder), the filters.dateRange.from and filters.dateRange.to branches read self.compare_operations[-1]. A placeholder that is not inside a comparison, such as numbers(dateDiff('day', {filters.dateRange.from}, now())) or a SELECT column, raises IndexError.
• On /api/query this becomes a 500. In MCP execute-sql, validation (ee/hogai/chat_agent/sql/mixins.py) catches only HogQL error types, so the error reaches the generic handler in products/posthog_ai/backend/api/mcp_tools.py and the agent sees "The tool raised an internal error".

Suggested fix: when there is no enclosing comparison, return the resolved date constant, or now() / an open bound. Otherwise raise a clear QueryError. Do not index an empty list. Add tests for placeholders in a table-function argument and in a select column.

6. The SQL line-chart tooltip repeats series rows

Status: confirmed when a chart has a breakdown and 2 or more Y columns · Impact: low to medium

• getSeriesKey (frontend/src/queries/nodes/DataVisualization/Components/Charts/sqlLineGraphAdapter.ts) returns only breakdownValue for breakdown series. When there are several Y columns, each column produces series with the same breakdownValue, so the keys collide. The tooltip (packages/quill/packages/charts/src/overlays/DefaultTooltip.tsx) uses key={s.series.key}, so React reuses rows. Closest-series highlighting and trend-line matching also break.

Suggested fix: include the column in the key, for example ${column}:${breakdownValue} (the column name is already available in seriesBreakdownLogic), and keep breakdownValue for the resultCustomizations lookup. Also remove duplicate chartSettings.yAxis entries that name the same column. Add an adapter unit test.

7. Tiles look blank on the dashboard grid but render on the insight page

Status: partly true · Impact: medium (it looks broken to headless or screenshot agents)

• shouldRenderInsightCardViz (frontend/src/lib/components/Cards/InsightCard/InsightCard.tsx) unmounts canvas charts (trends, SQL line and bar) when a tile is off-screen or document.hidden is true, and shows InsightVisualizationSkeleton instead. Headless browsers and background tabs therefore see grey skeletons. Missing tile layouts is not the cause, because default layouts apply.
• There is also a separate report of a real regression where chart tiles are blank and table tiles work. Investigate that one on its own.

Suggested fix: render every tile when DashboardPlacement.Export, a query flag, or a headless user agent is present. Also give the paused skeleton a small "Chart paused while hidden" label so that it does not look like missing data.

8. ClickHouse memory limit on minute-interval trends

Status: partly true · Impact: low to medium

• No guard limits the number of minute buckets (products/product_analytics/backend/hogql_queries/trends/trend_validation_rules.py has no interval rule). The failure does surface cleanly as a 513 clickhouse_memory_limit_exceeded with a "shorter range" hint. MCP classifies recoverable errors as 4xx, so it treats the 513 as unrecoverable.
• services/mcp/definitions/prompts/query-trends.md lists only hour, day, week and month, and does not mention minute or its limits.

Suggested fix: add a trends validation rule that limits interval: minute to about 1 day (and second to about 1 hour) and returns a 400 with a clear message. Treat 512 and 513 as agent-recoverable in the MCP error classification (services/mcp/src/lib/errors.ts). Document minute and its limit in query-trends.md.

9. Annotations do not show on SQL insights

Status: mostly an agent error · Impact: low

• Shipped in feat(insights): show annotations on SQL charts #90013. DataVisualization.tsx passes chartSettings.showAnnotations === true for a date x-axis, but the toggle defaults to off. MCP also removes showAnnotations (item 2), so an agent cannot turn it on.

Suggested fix: fixed by item 2, plus a line in the insight-create / insight-update description: "set chartSettings.showAnnotations: true on date x-axis SQL charts".

10. Feature request: heatmap or clickmap dashboard card

Status: valid feature request · Impact: low

• DashboardWidgetType (products/dashboards/backend/widget_specs/registry.py) has no heatmap widget. Saved heatmaps exist (products/web_analytics/backend/api/heatmaps_api.py), and elements-stats-retrieve gives click data over MCP.

Suggested fix: add a saved_heatmap widget spec that renders a saved heatmap screenshot with overlay, and expose it through dashboard-widgets-batch-add.

Suggested order: 2 and 3 are small and fix most of the "saves lose fields" complaints. 5 and 6 are small, self-contained bug fixes. 1 has the largest impact but needs a scope decision.

🤖 Generated with Claude Code