Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(mcp): let explain-chart evidence carry a chart of its own numbers (#124615)

Sam Penningtonadbd114ee126
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 9f6f583cf4df..274c492475e4 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -6442,6 +6442,8 @@ snapshots:
hash: v1.k794b7964.8d0d4e81255c25acbe114b45d698a66d4b3ff5be122c97eea1f5cc2066711a72.jx6b5OO_YEIBQZHEUccM0lJ6vaRZBUUWxs3dJgxxwKw
mcp-apps-explain-chart--summary--light:
hash: v1.k794b7964.8e544f3f6c9e2e43bf03efd6bf30e402e2f24a41ec060922b5e3068643ce4c86.BQcCbMIGeBusavfXWYInYZD6jMZfnN4zr-HV9oOAFHg
+ mcp-apps-explain-chart-evidence-chart--line--light:
+ hash: v1.k794b7964.d18367c8e6c0db146a8a61c780cca48fd38f21268db89318114be3fb65130bf8.vtgJK_jbQZbEXfmqXJhYI7BnuwvNkc68bAjvqAAlh_E
mcp-apps-feature-flags--boolean-flag--light:
hash: v1.k794b7964.f3ee0e724e30f350166b5a87d46cd36ba9f982735aa9d7e322aeaf28bc4c9b1c.KzlRVALZdoWS2mlKcnTJRTOo4SmFvIZzKhj6SodWt3I
mcp-apps-feature-flags--flag-list--light:
diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
index f2c3770425f1..1177d0b4935f 100644
--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
@@ -101,9 +101,9 @@ function StoryChart({ series, overlay }: { series: Series[]; overlay?: ReactNode
}
const evidenceCharts: StoryEvidenceCharts = {
- canShow: () => true,
+ canShow: (item) => !!item.query,
prefetch: () => {},
- render: (_, text) => (
+ render: ({ text }) => (
<StoryChart
series={BY_REFERRER.map((item, index) =>
isSeriesNamedIn([item.label, REFERRERS[index]!], text) ? item : { ...item, color: `${item.color}40` }
diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
index 17847f70f28b..c0ec8815c985 100644
--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
@@ -25,11 +25,11 @@ export interface StoryPageChange {
}
export interface StoryEvidenceCharts {
- canShow: (query: Record<string, unknown>) => boolean
- prefetch: (queries: Record<string, unknown>[]) => void
+ canShow: (item: StoryEvidence) => boolean
+ prefetch: (items: StoryEvidence[]) => void
/** Draws the chart, fading every series that the evidence's text does not name. */
- render: (query: Record<string, unknown>, text: string) => ReactNode
- onShow?: (query: Record<string, unknown>) => void
+ render: (item: StoryEvidence) => ReactNode
+ onShow?: (item: StoryEvidence) => void
}
export interface ExplainChartViewProps {
@@ -81,27 +81,25 @@ export function ExplainChartView({
const hasNext = activeIndex + 1 < pages.length
const shownEvidence: StoryEvidence | null =
shownEvidenceIndex === null ? null : (active.chapter?.evidence[shownEvidenceIndex] ?? null)
- const evidenceView =
- evidenceCharts && shownEvidence?.query ? { text: shownEvidence.text, query: shownEvidence.query } : null
+ const evidenceView = shownEvidence && evidenceCharts?.canShow(shownEvidence) ? shownEvidence : null
const prefetch = evidenceCharts?.prefetch
useEffect(() => {
- const queries = active.chapter?.evidence.flatMap((item) => (item.query ? [item.query] : [])) ?? []
- if (queries.length) {
- prefetch?.(queries)
+ if (active.chapter?.evidence.length) {
+ prefetch?.(active.chapter.evidence)
}
}, [active, prefetch])
- const canShowChart = (item: StoryEvidence): boolean => !!item.query && !!evidenceCharts?.canShow(item.query)
+ const canShowChart = (item: StoryEvidence): boolean => !!evidenceCharts?.canShow(item)
const toggleEvidenceChart = (index: number): void => {
- const query = active.chapter?.evidence[index]?.query
- if (index === shownEvidenceIndex || !query) {
+ const item = active.chapter?.evidence[index]
+ if (index === shownEvidenceIndex || !item) {
setShownEvidenceIndex(null)
return
}
setShownEvidenceIndex(index)
- evidenceCharts?.onShow?.(query)
+ evidenceCharts?.onShow?.(item)
}
const select = (index: number, source: StoryNavigationSource): void => {
@@ -143,7 +141,7 @@ export function ExplainChartView({
Back to the walkthrough
</Button>
</div>
- {evidenceCharts.render(evidenceView.query, evidenceView.text)}
+ {evidenceCharts.render(evidenceView)}
</>
) : (
<>
diff --git a/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsx b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsx
new file mode 100644
index 000000000000..fd0821dccf54
--- /dev/null
+++ b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsx
@@ -0,0 +1,51 @@
+import type { Meta, StoryFn, StoryObj } from '@storybook/react'
+import type { ReactElement } from 'react'
+
+import { McpThemeDecorator } from '@posthog/mcp-ui/storybook/decorator'
+import { useChartTheme } from '@posthog/quill-charts'
+
+import { StoryEvidenceChart } from './StoryEvidenceChart'
+
+// The chart measures its box with a ResizeObserver, so give it a definite width.
+const FixedWidth = (Story: StoryFn): ReactElement => (
+ <div className="w-[680px]">
+ <Story />
+ </div>
+)
+
+const meta: Meta = {
+ title: 'MCP Apps/Explain Chart/Evidence chart',
+ decorators: [McpThemeDecorator, FixedWidth],
+ parameters: { testOptions: { skipDarkMode: true } },
+}
+export default meta
+
+type Story = StoryObj<{}>
+
+function LineChart(): ReactElement {
+ return (
+ <StoryEvidenceChart
+ className="h-[260px]"
+ theme={useChartTheme()}
+ chart={{
+ type: 'line',
+ labels: [
+ 'Oct 26 18:00',
+ 'Oct 26 19:00',
+ 'Oct 26 20:00',
+ 'Oct 26 21:00',
+ 'Oct 26 22:00',
+ 'Oct 26 23:00',
+ ],
+ series: [
+ { name: 'EU hit rate', values: [0.91, 0.9, 0.55, 0.62, 0.7, 0.78] },
+ { name: 'US hit rate', values: [0.88, 0.89, 0.52, 0.6, 0.69, 0.8] },
+ ],
+ }}
+ />
+ )
+}
+
+export const Line: Story = {
+ render: () => <LineChart />,
+}
diff --git a/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsx b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsx
new file mode 100644
index 000000000000..1d3ca24121fb
--- /dev/null
+++ b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsx
@@ -0,0 +1,37 @@
+import type { ReactElement } from 'react'
+
+import { buildYTickFormatter, type ChartTheme, TimeSeriesBarChart, TimeSeriesLineChart } from '@posthog/quill-charts'
+
+import type { StoryEvidenceChartData } from './explainChartTypes'
+
+const Y_AXIS = { tickFormatter: buildYTickFormatter({ format: 'short' }), showGrid: true }
+
+export interface StoryEvidenceChartProps {
+ chart: StoryEvidenceChartData
+ theme: ChartTheme
+ className: string
+}
+
+export function StoryEvidenceChart({ chart, theme, className }: StoryEvidenceChartProps): ReactElement {
+ const series = chart.series.map((item, index) => ({ key: String(index), label: item.name, data: item.values }))
+ const legend = { show: series.length > 1 }
+ return (
+ <div className={`flex w-full flex-col ${className}`} data-attr="explain-chart-evidence-inline-chart">
+ {chart.type === 'bar' ? (
+ <TimeSeriesBarChart
+ series={series}
+ labels={chart.labels}
+ theme={theme}
+ config={{ yAxis: Y_AXIS, legend, barLayout: 'grouped' }}
+ />
+ ) : (
+ <TimeSeriesLineChart
+ series={series}
+ labels={chart.labels}
+ theme={theme}
+ config={{ yAxis: Y_AXIS, legend, showCrosshair: true }}
+ />
+ )}
+ </div>
+ )
+}
diff --git a/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts b/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts
index 1a17f099b9d7..88d67f3c6568 100644
--- a/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts
+++ b/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts
@@ -1,9 +1,16 @@
export type StoryConfidence = 'high' | 'medium' | 'low'
+export interface StoryEvidenceChartData {
+ type: 'line' | 'bar'
+ labels: string[]
+ series: { name: string; values: number[] }[]
+}
+
export interface StoryEvidence {
text: string
url: string | null
query?: Record<string, unknown> | null
+ chart?: StoryEvidenceChartData | null
}
export interface StoryChapter {
diff --git a/products/product_analytics/skills/investigate-metric/SKILL.md b/products/product_analytics/skills/investigate-metric/SKILL.md
index 3550d0df2603..baf626c173c1 100644
--- a/products/product_analytics/skills/investigate-metric/SKILL.md
+++ b/products/product_analytics/skills/investigate-metric/SKILL.md
@@ -97,7 +97,7 @@ When it is a walkthrough:
- Add "Show the walkthrough (Step 5)" as the last item of your plan or to-do list.
- Keep the `TrendsQuery` behind each finding, such as an event count with a breakdown or a property filter.
The walkthrough draws a `TrendsQuery` as a chart beside the finding, and any other query only as a link.
- Use SQL for the findings that a `TrendsQuery` cannot express.
+ Use SQL for the findings that a `TrendsQuery` cannot express, and pass its numbers as the evidence's `chart` so they draw too.
## Step 2 — Common opening moves
@@ -159,6 +159,7 @@ Map the investigation onto it:
- **Evidence** → `evidence`, each finding with the `query` that produced it, or a `url`
for a commit or a deploy. Pass the `TrendsQuery` you ran where you have one: the
walkthrough draws it as a chart, while any other query only becomes a link.
+ For a finding from SQL, also pass `chart` with the numbers from its result: `line` over time or `bar` per label, the `labels`, and one `series` per line.
- A **headline** of one sentence with no numbers sums up the whole chart.
Wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in `**double asterisks**` so the walkthrough highlights it.
Do the same in each `cause`.
diff --git a/services/mcp/schema/tool-inputs.json b/services/mcp/schema/tool-inputs.json
index cfc25eab86c0..f494fb55892f 100644
--- a/services/mcp/schema/tool-inputs.json
+++ b/services/mcp/schema/tool-inputs.json
@@ -729,6 +729,50 @@
},
"additionalProperties": {}
},
+ "chart": {
+ "description": "Numbers to draw beside this finding when its query is not a TrendsQuery, such as SQL. Copy them from the result you got.",
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": ["line", "bar"],
+ "description": "`line` for values over time, `bar` for a value per label."
+ },
+ "labels": {
+ "minItems": 1,
+ "maxItems": 200,
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "The x-axis labels in order, such as hours or referrers, written as the person should read them."
+ },
+ "series": {
+ "minItems": 1,
+ "maxItems": 6,
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 80
+ },
+ "values": {
+ "type": "array",
+ "items": {
+ "type": "number"
+ },
+ "description": "One value per label, in the same order."
+ }
+ },
+ "required": ["name", "values"]
+ }
+ }
+ },
+ "required": ["type", "labels", "series"]
+ },
"url": {
"description": "A link to the source when it is not a query, for example a commit, a pull request or a deploy.",
"type": "string",
diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.ts
index 61e62c5f0e0c..ce20e8e2017c 100644
--- a/services/mcp/src/schema/tool-inputs.ts
+++ b/services/mcp/src/schema/tool-inputs.ts
@@ -587,6 +587,33 @@ const ExplainChartEvidenceSchema = z.object({
.describe(
'The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the walkthrough.'
),
+ chart: z
+ .object({
+ type: z.enum(['line', 'bar']).describe('`line` for values over time, `bar` for a value per label.'),
+ labels: z
+ .array(z.string())
+ .min(1)
+ .max(200)
+ .describe(
+ 'The x-axis labels in order, such as hours or referrers, written as the person should read them.'
+ ),
+ series: z
+ .array(
+ z.object({
+ name: z.string().min(1).max(80),
+ values: z.array(z.number()).describe('One value per label, in the same order.'),
+ })
+ )
+ .min(1)
+ .max(6),
+ })
+ .refine((chart) => chart.series.every((item) => item.values.length === chart.labels.length), {
+ message: 'Each series needs one value per label.',
+ })
+ .optional()
+ .describe(
+ 'Numbers to draw beside this finding when its query is not a TrendsQuery, such as SQL. Copy them from the result you got.'
+ ),
url: z
.string()
.url()
diff --git a/services/mcp/src/tools/insights/explainChart.ts b/services/mcp/src/tools/insights/explainChart.ts
index 25b68fa27539..949db60079f4 100644
--- a/services/mcp/src/tools/insights/explainChart.ts
+++ b/services/mcp/src/tools/insights/explainChart.ts
@@ -176,6 +176,7 @@ export const explainChartHandler: ToolBase<typeof schema, Result>['handler'] = a
text: item.text,
url: item.query ? `${baseUrl}${newInsightPath(item.query)}` : (item.url ?? null),
query: item.query && redrawSchema.safeParse(item.query).success ? item.query : null,
+ chart: item.chart ?? null,
})),
}
})
diff --git a/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx b/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx
index bb453900f596..62b81f2d04a3 100644
--- a/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx
+++ b/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx
@@ -3,12 +3,15 @@ import { useCallback, useMemo, useRef, useState } from 'react'
import { Button, Text } from '@posthog/quill'
+import type { StoryEvidence } from 'products/product_analytics/mcp/apps/explainChart/explainChartTypes'
import type { StoryEvidenceCharts } from 'products/product_analytics/mcp/apps/explainChart/ExplainChartView'
+import { StoryEvidenceChart } from 'products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart'
import { isSeriesNamedIn } from 'products/product_analytics/mcp/apps/explainChart/storyNamedSeries'
import { capture } from '../analytics/posthog'
import { loadRenderUiData } from '../apps/render-ui-data'
import { AppLoadingState } from '../components/AppLoadingState'
+import { useMcpChartTheme } from '../components/charts/theme'
import { TrendsVisualizer } from '../components/TrendsVisualizer'
import type { TrendsQuery, TrendsResult, TrendsResultItem } from '../components/types'
import { getSeriesLabel } from '../components/utils'
@@ -26,7 +29,12 @@ function isTrendsQuery(query: Record<string, unknown>): boolean {
return query.kind === 'TrendsQuery' || (query.kind === undefined && Array.isArray(query.series))
}
+function trendsQueryOf(item: StoryEvidence): Record<string, unknown> | null {
+ return item.query && isTrendsQuery(item.query) ? item.query : null
+}
+
export function useEvidenceCharts(app: App | null, chartClassName: string): StoryEvidenceCharts | undefined {
+ const theme = useMcpChartTheme()
const [charts, setCharts] = useState<Record<string, EvidenceChart>>({})
const requested = useRef(new Set<string>())
@@ -67,7 +75,13 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor
)
const prefetch = useCallback(
- (queries: Record<string, unknown>[]): void => queries.filter(isTrendsQuery).forEach(load),
+ (items: StoryEvidence[]): void =>
+ items.forEach((item) => {
+ const query = trendsQueryOf(item)
+ if (query && !item.chart) {
+ load(query)
+ }
+ }),
[load]
)
@@ -76,15 +90,33 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor
return undefined
}
return {
- canShow: isTrendsQuery,
+ canShow: (item) => !!item.chart || !!trendsQueryOf(item),
prefetch,
- onShow: (query) => {
+ onShow: (item) => {
+ const query = item.chart ? null : trendsQueryOf(item)
capture('mcp_ui_app_explain_chart_evidence_chart_shown', {
- was_loaded: charts[JSON.stringify(query)]?.status === 'ready',
+ was_loaded: !query || charts[JSON.stringify(query)]?.status === 'ready',
+ inline: !!item.chart,
})
- load(query)
+ if (query) {
+ load(query)
+ }
},
- render: (query, text) => {
+ render: (item) => {
+ if (item.chart) {
+ return (
+ <StoryEvidenceChart
+ key={JSON.stringify(item.chart)}
+ chart={item.chart}
+ theme={theme}
+ className={chartClassName}
+ />
+ )
+ }
+ const query = trendsQueryOf(item)
+ if (!query) {
+ return null
+ }
const chart = charts[JSON.stringify(query)]
if (chart?.status === 'ready') {
return (
@@ -92,8 +124,8 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor
key={JSON.stringify(query)}
query={chart.query}
results={chart.results}
- highlightedSeries={chart.results.flatMap((item, index) =>
- isSeriesNamedIn(seriesNames(item, index), text) ? [index] : []
+ highlightedSeries={chart.results.flatMap((result, index) =>
+ isSeriesNamedIn(seriesNames(result, index), item.text) ? [index] : []
)}
showControls={false}
showTitle={false}
@@ -125,5 +157,5 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor
)
},
}
- }, [app, chartClassName, charts, load, prefetch])
+ }, [app, chartClassName, charts, load, prefetch, theme])
}
diff --git a/services/mcp/tests/unit/explain-chart.test.ts b/services/mcp/tests/unit/explain-chart.test.ts
index e6062c0f29c6..5e2a47d0f812 100644
--- a/services/mcp/tests/unit/explain-chart.test.ts
+++ b/services/mcp/tests/unit/explain-chart.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
+import { ExplainChartInputSchema } from '@/schema/tool-inputs'
import { explainChartHandler } from '@/tools/insights/explainChart'
import { findStoryRange, lastBucketInProgress } from '@/tools/insights/storyRanges'
import { type Context, POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY } from '@/tools/types'
@@ -131,6 +132,12 @@ describe('explain-chart', () => {
})
})
+ const hitRate = {
+ type: 'line' as const,
+ labels: ['20:00', '21:00'],
+ series: [{ name: 'hit rate', values: [0.9, 0.55] }],
+ }
+
it('keeps a chart only for evidence that query-trends can draw again', async () => {
const series = [{ kind: 'EventsNode', event: 'signed_up' }]
const drawable = {
@@ -156,17 +163,41 @@ describe('explain-chart', () => {
evidence: [
{ text: 'Chrome sent most of it.', query: drawable },
{ text: 'Safari stayed flat.', query: linkOnly },
+ {
+ text: 'The hit rate fell.',
+ query: { kind: 'HogQLQuery', query: 'SELECT 1' },
+ chart: hitRate,
+ },
],
},
],
})
- expect(result.chapters[0]!.evidence.map((item) => [item.query !== null, item.url !== null])).toEqual([
- [true, true],
- [false, true],
+ expect(
+ result.chapters[0]!.evidence.map((item) => [item.query !== null, item.chart ?? null, item.url !== null])
+ ).toEqual([
+ [true, null, true],
+ [false, null, true],
+ [false, hitRate, true],
])
})
+ it('refuses a chart whose series do not have one value per label', () => {
+ const parsed = ExplainChartInputSchema.safeParse({
+ insightId: 'abc12345',
+ headline: 'One day stands out.',
+ chapters: [
+ {
+ title: 'A spike on October 2',
+ start: '2026-10-02',
+ evidence: [{ text: 'The hit rate fell.', chart: { ...hitRate, labels: ['20:00'] } }],
+ },
+ ],
+ })
+
+ expect(parsed.success).toBe(false)
+ })
+
it.each([
['a day that is still running', ['2026-10-17', '2026-10-18'], 'day', 'UTC', '2026-10-18T10:00:00Z', true],
['a day that has ended', ['2026-10-16', '2026-10-17'], 'day', 'UTC', '2026-10-18T10:00:00Z', false],