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-analytics): track first data seen live and add onboarding door (#128682)

Lucas Fariaa3fcbb92c9ab
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 1034dd06928b..a95dafdda4c3 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -14379,7 +14379,7 @@ snapshots:
scenes-app-mcp-analytics-setup-mode--connect--narrow--light:
hash: v1.k794b7964.6542164c597b7c1aa986692e2d8a5a82112e90d6da8c66b537e628ee7dcf5537.Z3O_dXd68uJ3N9YU7hVxIykCexZf4WAgDyZeHVD0Wmc
scenes-app-mcp-analytics-setup-mode--connected--dark:
- hash: v1.k794b7964.77072714a17f84134a2752578e6313842eeebd4a707ed266ad2433fba22e05b9.mWZzk88fOQu9CdfTlp9cn86pi0nZJs8jZbgYUSD-zWE
+ hash: v1.k794b7964.b16f45f62a2da9aad6c7e91131e53549d2e7c15ec02cb36093a832052291d0cf.YhU8WIG9_EpcPaDqv9nNAo5qR430sOAAXkGcswifh5Q
scenes-app-mcp-analytics-setup-mode--connected--light:
hash: v1.k794b7964.0d7807c3aab3147e4625e4d1cdb96b3988f5e806906112949b92a97bc8b66ee0.nLcykpqr6QAQlCBbDGa0fI81VvshoeMKyJ4lVnGooko
scenes-app-mcp-analytics-setup-mode--first-call-success--dark:
@@ -14413,7 +14413,7 @@ snapshots:
scenes-app-mcp-analytics-setup-mode--setup-screen--wide--dark:
hash: v1.k794b7964.14df4e985a137acce35bcfc84d6e785fc90ce98886238876ae435c0cfa65f620.mOKsTD1FL_hccqrWvGCa9oibfUb1Jw1Ew2jXWE7TaU4
scenes-app-mcp-analytics-setup-mode--setup-screen--wide--light:
- hash: v1.k794b7964.505ff5df232240368925a64659f8ed56aff9facdd0e19ce4b879eed256386bef.BTKCbY-gvZi2FPrY8pu-oSDUiTWaeMaZU9QJOkRBK6Q
+ hash: v1.k794b7964.7edf17fea0da5cceab85018af746f63c0f4b3dc036f188dba0a9f37cd4fc8450.qShFhbI2HtZ9w3PYw7jX0QNIrYoNDwHG2AmvuzwBdbI
scenes-app-mcp-analytics-tool-detail--tool-detail--medium--dark:
hash: v1.k794b7964.a7af68eb4dc02ec4836cccf316978762d8df8627c24aefe551c09f7fe97ec8b4.gMBAhuXSBaeSvK0J4nddD5Vb51J_MOkXul4IRXhcCPM
scenes-app-mcp-analytics-tool-detail--tool-detail--medium--light:
diff --git a/products/mcp_analytics/frontend/FirstDataSeen.test.tsx b/products/mcp_analytics/frontend/FirstDataSeen.test.tsx
new file mode 100644
index 000000000000..ecffd1f7de77
--- /dev/null
+++ b/products/mcp_analytics/frontend/FirstDataSeen.test.tsx
@@ -0,0 +1,97 @@
+import { cleanup, render } from '@testing-library/react'
+import { router } from 'kea-router'
+import { expectLogic } from 'kea-test-utils'
+import posthog from 'posthog-js'
+
+import api from 'lib/api'
+import { FEATURE_FLAGS } from 'lib/constants'
+import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
+import { sceneLogic } from 'scenes/sceneLogic'
+import { urls } from 'scenes/urls'
+
+import { initKeaTests } from '~/test/init'
+
+import { FirstDataSeen } from './FirstDataSeen'
+import { type FirstDataSurface, mcpAnalyticsOnboardingLogic } from './mcpAnalyticsOnboardingLogic'
+import { MCPAnalyticsScene } from './MCPAnalyticsScene'
+import { mcpAnalyticsSceneLogic } from './mcpAnalyticsSceneLogic'
+import { mcpSetupModeLogic } from './setupMode/mcpSetupModeLogic'
+
+jest.mock('lib/api')
+jest.mock('lib/utils/product-intents', () => ({ addProductIntent: jest.fn() }))
+
+const mockApi = api as jest.Mocked<typeof api>
+
+// Signal row shape: [has_initialize, tool_calls_total, tool_calls_7d, first_call_at]
+const CONNECTED = [1, 0, 0, '1970-01-01T00:00:00Z']
+const ONE_CALL = [1, 1, 1, '2026-07-01T00:00:00Z']
+
+/** `mountHost` runs after the signal mocks are in place, because the logics it mounts query the signals too. */
+async function arriveLive(
+ mountHost: () => void = () => {}
+): Promise<ReturnType<typeof mcpAnalyticsOnboardingLogic.build>> {
+ jest.spyOn(mockApi, 'query')
+ .mockReset()
+ .mockResolvedValueOnce({ results: [CONNECTED] } as any)
+ .mockResolvedValue({ results: [ONE_CALL] } as any)
+ mountHost()
+ const logic = mcpAnalyticsOnboardingLogic()
+ logic.mount()
+ await expectLogic(logic).toFinishAllListeners()
+ logic.actions.loadSignals()
+ await expectLogic(logic).toFinishAllListeners()
+ expect(logic.values.firstDataWatch).toBe('arrived')
+ return logic
+}
+
+describe('FirstDataSeen', () => {
+ beforeEach(() => {
+ initKeaTests()
+ })
+
+ afterEach(() => {
+ cleanup()
+ jest.restoreAllMocks()
+ })
+
+ it.each<[string, boolean, FirstDataSurface]>([
+ ['the dashboard', false, 'dashboard'],
+ ['setup mode', true, 'setup_mode'],
+ ])('settles an arrival seen in %s and captures where', async (_label, inSetupMode, surface) => {
+ const capture = jest.spyOn(posthog, 'capture').mockImplementation(() => undefined)
+ const logic = await arriveLive(() => {
+ if (inSetupMode) {
+ featureFlagLogic.actions.setFeatureFlags([], { [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]: true })
+ router.actions.push(urls.mcpAnalyticsDashboard(), { setup: 'agent' })
+ mcpSetupModeLogic.mount()
+ }
+ })
+
+ render(<FirstDataSeen />)
+
+ expect(logic.values.firstDataWatch).toBe('settled')
+ expect(capture).toHaveBeenCalledWith(
+ 'mcp analytics first data seen live',
+ expect.objectContaining({ surface }),
+ undefined
+ )
+ })
+
+ it('settles an arrival on a tab the scene renders as not found', async () => {
+ jest.spyOn(posthog, 'capture').mockImplementation(() => undefined)
+ const logic = await arriveLive(() => {
+ sceneLogic.mount()
+ sceneLogic.actions.setExportedScene({} as any, 'MCPAnalytics', 'mcpAnalyticsIntentClustering', {
+ params: {},
+ searchParams: {},
+ hashParams: {},
+ })
+ mcpAnalyticsSceneLogic().mount()
+ })
+
+ const { getByText } = render(<MCPAnalyticsScene />)
+
+ expect(getByText('Page not found')).toBeTruthy()
+ expect(logic.values.firstDataWatch).toBe('settled')
+ })
+})
diff --git a/products/mcp_analytics/frontend/FirstDataSeen.tsx b/products/mcp_analytics/frontend/FirstDataSeen.tsx
new file mode 100644
index 000000000000..374bac1b63db
--- /dev/null
+++ b/products/mcp_analytics/frontend/FirstDataSeen.tsx
@@ -0,0 +1,20 @@
+import { useActions, useValues } from 'kea'
+import { useEffect } from 'react'
+
+import { mcpAnalyticsOnboardingLogic } from './mcpAnalyticsOnboardingLogic'
+import { mcpSetupModeLogic } from './setupMode/mcpSetupModeLogic'
+
+/** Records that the viewer was on the page when their first tool call landed. */
+export function FirstDataSeen(): null {
+ const { firstDataWatch } = useValues(mcpAnalyticsOnboardingLogic)
+ const { acknowledgeFirstData } = useActions(mcpAnalyticsOnboardingLogic)
+
+ useEffect(() => {
+ if (firstDataWatch === 'arrived') {
+ // Looked up rather than connected: with the setup mode flag off, its logic never mounts.
+ acknowledgeFirstData(mcpSetupModeLogic.findMounted()?.values.isOpen ? 'setup_mode' : 'dashboard')
+ }
+ }, [firstDataWatch, acknowledgeFirstData])
+
+ return null
+}
diff --git a/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx b/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
index 3f288ae7f634..8a536c6b57d6 100644
--- a/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
+++ b/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
@@ -19,6 +19,7 @@ import { SceneExport } from '~/scenes/sceneTypes'
import { MCPAnalyticsClustering } from './clustering/MCPAnalyticsClustering'
import { MCPAnalyticsActivityDashboard } from './earlyData/MCPAnalyticsEarlyData'
import { mcpAnalyticsEmptyState } from './emptyState/mcpAnalyticsEmptyState'
+import { FirstDataSeen } from './FirstDataSeen'
import { MCPAnalyticsDashboard } from './MCPAnalyticsDashboard'
import { mcpAnalyticsOnboardingLogic } from './mcpAnalyticsOnboardingLogic'
import { MCPAnalyticsTab, TAB_DESCRIPTIONS, mcpAnalyticsSceneLogic } from './mcpAnalyticsSceneLogic'
@@ -40,6 +41,15 @@ export const scene: SceneExport = {
const MCP_DOCS_URL = 'https://posthog.com/docs/mcp-analytics/installation'
export function MCPAnalyticsScene(): JSX.Element {
+ return (
+ <>
+ <FirstDataSeen />
+ <MCPAnalyticsSceneBody />
+ </>
+ )
+}
+
+function MCPAnalyticsSceneBody(): JSX.Element {
const { searchParams } = useValues(router)
const { activeTab } = useValues(mcpAnalyticsSceneLogic)
const { onboardingState } = useValues(mcpAnalyticsOnboardingLogic)
diff --git a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.test.ts b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.test.ts
index eb334629e6be..c93fafc2945c 100644
--- a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.test.ts
+++ b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.test.ts
@@ -1,13 +1,21 @@
import { expectLogic } from 'kea-test-utils'
+import posthog from 'posthog-js'
import api from 'lib/api'
import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'
import { teamLogic } from 'scenes/teamLogic'
+import { userLogic } from 'scenes/userLogic'
import { ProductKey } from '~/queries/schema/schema-general'
import { initKeaTests } from '~/test/init'
-import { mcpAnalyticsOnboardingLogic } from './mcpAnalyticsOnboardingLogic'
+import {
+ FirstDataSurface,
+ FirstDataWatch,
+ MCPOnboardingSignals,
+ mcpAnalyticsOnboardingLogic,
+ nextFirstDataWatch,
+} from './mcpAnalyticsOnboardingLogic'
jest.mock('lib/api')
@@ -142,4 +150,169 @@ describe('mcpAnalyticsOnboardingLogic', () => {
expect(setupLogic.values.setupAttempt).toMatchObject({ id: attemptId, completed: true })
}
)
+
+ describe('first data watch', () => {
+ const FIRST_DATA_EVENT = 'mcp analytics first data seen live'
+ const EPOCH = '1970-01-01T00:00:00Z'
+ const FIRST_CALL_AT = '2026-07-01T00:00:00Z'
+
+ const signalsWith = (toolCallsTotal: number, toolCalls7d: number = toolCallsTotal): MCPOnboardingSignals => ({
+ hasInitialize: true,
+ hasToolCall: toolCallsTotal > 0,
+ toolCallsTotal,
+ toolCalls7d,
+ firstCallAt: toolCallsTotal > 0 ? FIRST_CALL_AT : null,
+ })
+ const NO_CALLS = signalsWith(0)
+ const ONE_CALL = signalsWith(1)
+ const BACKFILL_LIFETIME = signalsWith(300, 0)
+ const BACKFILL_DENSE_WEEK = signalsWith(260, 250)
+
+ it.each<{
+ current: FirstDataWatch
+ when: string
+ signals: MCPOnboardingSignals | null
+ expected: FirstDataWatch
+ }>([
+ { current: 'unknown', when: 'no answer', signals: null, expected: 'unknown' },
+ { current: 'unknown', when: 'no calls', signals: NO_CALLS, expected: 'watching' },
+ { current: 'unknown', when: 'one call', signals: ONE_CALL, expected: 'settled' },
+ { current: 'watching', when: 'no answer', signals: null, expected: 'watching' },
+ { current: 'watching', when: 'no calls', signals: NO_CALLS, expected: 'watching' },
+ { current: 'watching', when: 'one call', signals: ONE_CALL, expected: 'arrived' },
+ { current: 'watching', when: '300 lifetime calls', signals: BACKFILL_LIFETIME, expected: 'settled' },
+ { current: 'watching', when: '250 calls this week', signals: BACKFILL_DENSE_WEEK, expected: 'settled' },
+ { current: 'arrived', when: 'no answer', signals: null, expected: 'arrived' },
+ { current: 'arrived', when: 'no calls', signals: NO_CALLS, expected: 'arrived' },
+ { current: 'arrived', when: '300 lifetime calls', signals: BACKFILL_LIFETIME, expected: 'arrived' },
+ { current: 'settled', when: 'no answer', signals: null, expected: 'settled' },
+ { current: 'settled', when: 'no calls', signals: NO_CALLS, expected: 'settled' },
+ { current: 'settled', when: 'one call', signals: ONE_CALL, expected: 'settled' },
+ ])('$current + $when -> $expected', ({ current, signals, expected }) => {
+ expect(nextFirstDataWatch(current, signals)).toBe(expected)
+ })
+
+ type Row = [has_initialize: number, tool_calls_total: number, tool_calls_7d: number, first_call_at: string]
+ const NOT_INSTRUMENTED: Row = [0, 0, 0, EPOCH]
+ const CONNECTED: Row = [1, 0, 0, EPOCH]
+ const ONE: Row = [1, 1, 1, FIRST_CALL_AT]
+ const TWO: Row = [1, 2, 2, FIRST_CALL_AT]
+ const BACKFILL: Row = [1, 300, 300, FIRST_CALL_AT]
+
+ let captureSpy: jest.SpyInstance
+ beforeEach(() => {
+ captureSpy = jest.spyOn(posthog, 'capture').mockImplementation(() => undefined)
+ })
+ afterEach(() => {
+ captureSpy.mockRestore()
+ })
+
+ const firstDataCaptures = (): unknown[][] =>
+ captureSpy.mock.calls.filter(([event]) => event === FIRST_DATA_EVENT)
+
+ async function play(
+ steps: (Row | 'acknowledge' | 'acknowledge in setup mode')[]
+ ): Promise<ReturnType<typeof mcpAnalyticsOnboardingLogic.build>> {
+ const query = jest.spyOn(mockApi, 'query').mockReset()
+ steps
+ .filter((step): step is Row => Array.isArray(step))
+ .forEach((row) => {
+ query.mockResolvedValueOnce({ results: [row] } as any)
+ })
+ const logic = mcpAnalyticsOnboardingLogic()
+ logic.mount()
+ await expectLogic(logic).toFinishAllListeners()
+ for (const step of steps.slice(1)) {
+ if (step === 'acknowledge' || step === 'acknowledge in setup mode') {
+ logic.actions.acknowledgeFirstData(step === 'acknowledge' ? 'dashboard' : 'setup_mode')
+ } else {
+ logic.actions.loadSignals()
+ }
+ await expectLogic(logic).toFinishAllListeners()
+ }
+ return logic
+ }
+
+ it.each<[string, Parameters<typeof play>[0], FirstDataWatch, number]>([
+ [
+ 'a flip while watching arrives and captures once when acknowledged',
+ [NOT_INSTRUMENTED, ONE, 'acknowledge'],
+ 'settled',
+ 1,
+ ],
+ ['a flip from connected-no-calls arrives', [CONNECTED, ONE, 'acknowledge'], 'settled', 1],
+ ['an arrival stays armed across polls until acknowledged', [CONNECTED, ONE, TWO, TWO], 'arrived', 0],
+ ['a page load with data never arms', [ONE, TWO, 'acknowledge'], 'settled', 0],
+ ['a >=300-call backfill settles without arming', [CONNECTED, BACKFILL, 'acknowledge'], 'settled', 0],
+ ['later polls never refire after acknowledging', [CONNECTED, ONE, 'acknowledge', TWO, TWO], 'settled', 1],
+ ['a double acknowledge captures once', [CONNECTED, ONE, 'acknowledge', 'acknowledge'], 'settled', 1],
+ ])('%s', async (_name, steps, expectedWatch, expectedCaptures) => {
+ const logic = await play(steps)
+
+ expect(logic.values.firstDataWatch).toBe(expectedWatch)
+ expect(firstDataCaptures()).toHaveLength(expectedCaptures)
+ })
+
+ it('a failed poll in between still arrives on the next answer', async () => {
+ jest.spyOn(mockApi, 'query')
+ .mockReset()
+ .mockResolvedValueOnce({ results: [CONNECTED] } as any)
+ .mockRejectedValueOnce(new Error('query failed'))
+ .mockResolvedValueOnce({ results: [ONE] } as any)
+ const logic = mcpAnalyticsOnboardingLogic()
+ logic.mount()
+ await expectLogic(logic).toFinishAllListeners()
+ logic.actions.loadSignals()
+ await expectLogic(logic).toFinishAllListeners()
+ logic.actions.loadSignals()
+ await expectLogic(logic).toFinishAllListeners()
+
+ expect(logic.values.firstDataWatch).toBe('arrived')
+ })
+
+ it.each<FirstDataSurface>(['dashboard', 'setup_mode'])(
+ 'captures the live arrival seen in %s',
+ async (surface) => {
+ jest.useFakeTimers({
+ now: new Date('2026-07-01T00:01:30Z'),
+ doNotFake: [
+ 'setTimeout',
+ 'clearTimeout',
+ 'setInterval',
+ 'clearInterval',
+ 'setImmediate',
+ 'clearImmediate',
+ 'nextTick',
+ 'queueMicrotask',
+ 'performance',
+ 'requestAnimationFrame',
+ 'cancelAnimationFrame',
+ 'requestIdleCallback',
+ 'cancelIdleCallback',
+ 'hrtime',
+ ],
+ })
+ try {
+ await play([CONNECTED, ONE, surface === 'setup_mode' ? 'acknowledge in setup mode' : 'acknowledge'])
+ } finally {
+ jest.useRealTimers()
+ }
+
+ expect(captureSpy).toHaveBeenCalledWith(
+ FIRST_DATA_EVENT,
+ { tool_calls_total: 1, seconds_since_first_call: 90, surface },
+ undefined
+ )
+ }
+ )
+
+ it('settles without capturing during an impersonated session', async () => {
+ userLogic.actions.loadUserSuccess({ ...userLogic.values.user!, is_impersonated: true })
+
+ const logic = await play([CONNECTED, ONE, 'acknowledge'])
+
+ expect(logic.values.firstDataWatch).toBe('settled')
+ expect(firstDataCaptures()).toHaveLength(0)
+ })
+ })
})
diff --git a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts
index c574ef2c4ede..8e80eb935527 100644
--- a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts
+++ b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts
@@ -1,9 +1,11 @@
-import { MakeLogicType, afterMount, connect, kea, listeners, path, selectors } from 'kea'
+import { MakeLogicType, actions, afterMount, connect, kea, listeners, path, reducers, selectors } from 'kea'
import { loaders } from 'kea-loaders'
import api from 'lib/api'
import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'
import type { ProductSetupStatus } from 'lib/components/ProductEmptyState/types'
+import { dayjs } from 'lib/dayjs'
+import posthog from 'lib/posthog-typed'
import { addProductIntent } from 'lib/utils/product-intents'
import { teamLogic } from 'scenes/teamLogic'
import { userLogic } from 'scenes/userLogic'
@@ -62,6 +64,35 @@ export interface MCPOnboardingSignals {
firstCallAt: string | null
}
+function dashboardStageForSignals(signals: MCPOnboardingSignals | null): MCPDashboardStage | null {
+ if (!signals || !signals.hasToolCall) {
+ return null
+ }
+ return signals.toolCallsTotal >= METRICS_UNLOCK_LIFETIME_CALLS || signals.toolCalls7d >= METRICS_UNLOCK_7D_CALLS
+ ? 'metrics'
+ : 'activity'
+}
+
+export type FirstDataWatch = 'unknown' | 'watching' | 'arrived' | 'settled'
+
+/** Where the viewer saw the first call land: the setup mode reveal, or the scene the gate swaps in. */
+export type FirstDataSurface = 'setup_mode' | 'dashboard'
+
+/** A `null` answer (stale response after a project switch) changes nothing. */
+export function nextFirstDataWatch(current: FirstDataWatch, signals: MCPOnboardingSignals | null): FirstDataWatch {
+ if (!signals) {
+ return current
+ }
+ if (current === 'unknown') {
+ return signals.hasToolCall ? 'settled' : 'watching'
+ }
+ if (current === 'watching' && signals.hasToolCall) {
+ // A backfill that lands on the metrics stage is not a "your first call arrived" moment.
+ return dashboardStageForSignals(signals) === 'activity' ? 'arrived' : 'settled'
+ }
+ return current
+}
+
// Signal funnel over all history. `$mcp_initialize` fires when an agent connects
// (before any tool call), so it distinguishes "instrumented but no traffic yet"
// from "not instrumented at all". Counts (not booleans) so the same query drives
@@ -88,6 +119,7 @@ const POLL_INTERVAL_MS = 20000
export interface mcpAnalyticsOnboardingLogicValues {
setupStatus: ProductSetupStatus // productSetupStatusLogic
dashboardStage: MCPDashboardStage | null
+ firstDataWatch: FirstDataWatch
isOnboarded: boolean
onboardingState: MCPOnboardingState | null
signals: MCPOnboardingSignals | null
@@ -99,6 +131,9 @@ export interface mcpAnalyticsOnboardingLogicActions {
setDetectedStatus: (status: ProductSetupStatus) => {
status: ProductSetupStatus
} // productSetupStatusLogic
+ acknowledgeFirstData: (surface: FirstDataSurface) => {
+ surface: FirstDataSurface
+ }
loadSignals: (_: void) => void
loadSignalsFailure: (
error: string,
@@ -138,6 +173,9 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(
actions: [productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }), ['setDetectedStatus']],
values: [productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }), ['status as setupStatus']],
})),
+ actions({
+ acknowledgeFirstData: (surface: FirstDataSurface) => ({ surface }),
+ }),
loaders({
signals: {
__default: null as MCPOnboardingSignals | null,
@@ -185,6 +223,15 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(
},
},
}),
+ reducers({
+ firstDataWatch: [
+ 'unknown' as FirstDataWatch,
+ {
+ loadSignalsSuccess: (state, { signals }) => nextFirstDataWatch(state, signals),
+ acknowledgeFirstData: (state) => (state === 'arrived' ? 'settled' : state),
+ },
+ ],
+ }),
selectors({
onboardingState: [
(s) => [s.signals],
@@ -207,18 +254,10 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(
],
dashboardStage: [
(s) => [s.signals],
- (signals: MCPOnboardingSignals | null): MCPDashboardStage | null => {
- if (!signals || !signals.hasToolCall) {
- return null
- }
- return signals.toolCallsTotal >= METRICS_UNLOCK_LIFETIME_CALLS ||
- signals.toolCalls7d >= METRICS_UNLOCK_7D_CALLS
- ? 'metrics'
- : 'activity'
- },
+ (signals: MCPOnboardingSignals | null): MCPDashboardStage | null => dashboardStageForSignals(signals),
],
}),
- listeners(({ actions, values, cache }) => ({
+ listeners(({ actions, values, cache, selectors }) => ({
loadSignalsFailure: () => {
// A failing signal query must not strand the empty-state gate on its
// spinner. If nothing (preload included) has answered yet, publish
@@ -257,6 +296,18 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(
cache.disposables.dispose('poll')
}
},
+ acknowledgeFirstData: ({ surface }, _breakpoint, _action, previousState) => {
+ // Compare with the state before the reducer settled it, so a repeated acknowledge captures nothing.
+ if (selectors.firstDataWatch(previousState) !== 'arrived' || isImpersonatedSession()) {
+ return
+ }
+ const { toolCallsTotal, firstCallAt } = values.signals ?? {}
+ posthog.captureRaw('mcp analytics first data seen live', {
+ tool_calls_total: toolCallsTotal,
+ seconds_since_first_call: firstCallAt ? Math.max(0, dayjs().diff(dayjs(firstCallAt), 'second')) : null,
+ surface,
+ })
+ },
})),
afterMount(({ actions, cache, values }) => {
actions.loadSignals()
diff --git a/products/mcp_analytics/frontend/onboarding/steps.test.tsx b/products/mcp_analytics/frontend/onboarding/steps.test.tsx
new file mode 100644
index 000000000000..a65b2c2f0973
--- /dev/null
+++ b/products/mcp_analytics/frontend/onboarding/steps.test.tsx
@@ -0,0 +1,83 @@
+import { MOCK_DEFAULT_TEAM } from 'lib/api.mock'
+
+import { act, cleanup, render } from '@testing-library/react'
+import { router } from 'kea-router'
+import { expectLogic } from 'kea-test-utils'
+
+import api from 'lib/api'
+import { FEATURE_FLAGS } from 'lib/constants'
+import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
+import { removeProjectIdIfPresent } from 'lib/utils/kea-router'
+import { onboardingLogic } from 'scenes/onboarding/onboardingLogic'
+import { teamLogic } from 'scenes/teamLogic'
+
+import { initKeaTests } from '~/test/init'
+
+import { mcpAnalyticsOnboardingLogic } from '../mcpAnalyticsOnboardingLogic'
+import { resetSetupModeTrackingForTests } from '../setupMode/mcpSetupModeLogic'
+import { mcpAnalyticsOnboarding } from './steps'
+
+jest.mock('lib/api')
+jest.mock('lib/utils/product-intents', () => ({ addProductIntent: jest.fn() }))
+jest.mock('scenes/onboarding/OnboardingStep', () => ({
+ OnboardingStep: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+}))
+// The animated sidebar is not what this test is about, and it needs layout APIs jsdom lacks.
+jest.mock('../emptyState/MCPSetupSidebar', () => ({ MCPSetupSidebar: () => null }))
+
+// Signal row shape: [has_initialize, tool_calls_total, tool_calls_7d, first_call_at]
+const CONNECTED = [1, 0, 0, '1970-01-01T00:00:00Z']
+const ONE_CALL = [1, 1, 1, '2026-07-01T00:00:00Z']
+
+describe('mcpAnalyticsOnboarding install step', () => {
+ beforeEach(() => {
+ initKeaTests()
+ resetSetupModeTrackingForTests()
+ featureFlagLogic.actions.setFeatureFlags([], { [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]: true })
+ })
+
+ afterEach(() => {
+ cleanup()
+ jest.restoreAllMocks()
+ })
+
+ async function renderInstallStepAndLandFirstCall(): Promise<{ overlayShown: () => boolean }> {
+ jest.spyOn(api, 'query').mockResolvedValue({ results: [CONNECTED] } as any)
+ jest.spyOn(api, 'get').mockResolvedValue({ recent_calls: [] } as any)
+ // Hold the completion request open, so the redirect to the scene never happens during the test.
+ jest.spyOn(api, 'update').mockReturnValue(new Promise(() => {}))
+ router.actions.push('/onboarding/mcp_analytics', { step: 'install', setup: 'agent' })
+ const [installStep] = mcpAnalyticsOnboarding.steps({
+ featureFlags: { [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]: true },
+ } as any)
+ render(<>{installStep.render()}</>)
+ await act(async () => {
+ await expectLogic(mcpAnalyticsOnboardingLogic).toFinishAllListeners()
+ })
+ const overlayShown = (): boolean => !!document.querySelector('[data-attr="mcp-analytics-setup-mode"]')
+ expect(overlayShown()).toBe(true)
+
+ jest.spyOn(api, 'query').mockResolvedValue({ results: [ONE_CALL] } as any)
+ await act(async () => {
+ mcpAnalyticsOnboardingLogic.actions.loadSignals()
+ await expectLogic(mcpAnalyticsOnboardingLogic).toFinishAllListeners()
+ })
+ return { overlayShown }
+ }
+
+ it('keeps setup mode on screen while onboarding completes after the first call', async () => {
+ const { overlayShown } = await renderInstallStepAndLandFirstCall()
+
+ expect(overlayShown()).toBe(true)
+ })
+
+ it('sends the viewer to a destination chosen before onboarding started, not to the scene', async () => {
+ teamLogic.actions.loadCurrentTeamSuccess(MOCK_DEFAULT_TEAM)
+ onboardingLogic.mount()
+ onboardingLogic.actions.setOnCompleteOnboardingRedirectUrl('/insights')
+
+ await renderInstallStepAndLandFirstCall()
+
+ expect(removeProjectIdIfPresent(router.values.location.pathname)).toBe('/insights')
+ })
+})
diff --git a/products/mcp_analytics/frontend/onboarding/steps.tsx b/products/mcp_analytics/frontend/onboarding/steps.tsx
index fb8edc245162..651286498910 100644
--- a/products/mcp_analytics/frontend/onboarding/steps.tsx
+++ b/products/mcp_analytics/frontend/onboarding/steps.tsx
@@ -1,15 +1,25 @@
import { useActions, useValues } from 'kea'
-import { useEffect } from 'react'
+import { combineUrl, router } from 'kea-router'
+import { useEffect, useRef, useState } from 'react'
+import { Spinner } from '@posthog/lemon-ui'
+
+import { ProductEmptyState } from 'lib/components/ProductEmptyState/ProductEmptyState'
+import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'
+import { FEATURE_FLAGS } from 'lib/constants'
import { onboardingLogic } from 'scenes/onboarding/onboardingLogic'
import { OnboardingStep } from 'scenes/onboarding/OnboardingStep'
import { availableOnboardingProducts } from 'scenes/onboarding/shared/utils'
import { type ProductOnboardingProvider } from 'scenes/onboarding/types'
+import { urls } from 'scenes/urls'
import { ProductKey } from '~/queries/schema/schema-general'
import { OnboardingStepKey } from '~/types'
+import { mcpAnalyticsEmptyState } from '../emptyState/mcpAnalyticsEmptyState'
import { mcpAnalyticsOnboardingLogic } from '../mcpAnalyticsOnboardingLogic'
+import { MCPSetupMode } from '../setupMode/MCPSetupMode'
+import { SETUP_PARAM, SETUP_STEP_PARAM } from '../setupMode/setupMode'
import { MCPAnalyticsInstallHero } from './MCPAnalyticsInstall'
function MCPAnalyticsInstallStep(): JSX.Element {
@@ -37,6 +47,64 @@ function MCPAnalyticsInstallStep(): JSX.Element {
)
}
+/** The scene's own setup screen, so onboarding and the scene never show two different install flows. */
+function MCPAnalyticsSetupDoorStep(): JSX.Element {
+ const { onboardingState } = useValues(mcpAnalyticsOnboardingLogic)
+ const { status } = useValues(productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }))
+ const { searchParams } = useValues(router)
+ const { onCompleteOnboardingRedirectUrlOverride } = useValues(onboardingLogic)
+ const { completeOnboarding, setOnCompleteOnboardingRedirectUrl } = useActions(onboardingLogic)
+ // A destination picked before onboarding started (a `next` link) wins over the scene.
+ const [chosenDestination] = useState(onCompleteOnboardingRedirectUrlOverride)
+ // Setup mode lives in the URL, so carrying its params keeps the first-call reveal open in the scene.
+ const sceneUrl = combineUrl(urls.mcpAnalytics(), {
+ [SETUP_PARAM]: searchParams[SETUP_PARAM],
+ [SETUP_STEP_PARAM]: searchParams[SETUP_STEP_PARAM],
+ }).url
+ const latestSceneUrl = useRef(sceneUrl)
+ latestSceneUrl.current = sceneUrl
+
+ useEffect(() => {
+ if (onboardingState === 'onboarded') {
+ completeOnboarding(chosenDestination ? undefined : { redirectUrlOverride: latestSceneUrl.current })
+ }
+ }, [onboardingState, completeOnboarding, chosenDestination])
+
+ // The redirect runs after the completion request saves. Setup mode can close or move on meanwhile.
+ useEffect(() => {
+ if (!chosenDestination && onboardingLogic.findMounted()?.values.isCompleting) {
+ setOnCompleteOnboardingRedirectUrl(sceneUrl)
+ }
+ }, [sceneUrl, chosenDestination, setOnCompleteOnboardingRedirectUrl])
+
+ return (
+ <OnboardingStep
+ title={`Install ${availableOnboardingProducts[ProductKey.MCP_ANALYTICS].name}`}
+ stepKey={OnboardingStepKey.INSTALL}
+ continueText="Go to dashboard"
+ hideTitle
+ fullWidth
+ >
+ {status !== 'loading' && status !== 'has-data' ? (
+ <ProductEmptyState
+ config={{ ...mcpAnalyticsEmptyState.config, skippable: false }}
+ // A failed detection still gets the install screen, rather than a spinner that never ends.
+ mode={status === 'waiting-for-data' ? 'waiting-for-data' : 'needs-setup'}
+ />
+ ) : (
+ <>
+ {/* Loading, or data just landed and the effect above redirects to the scene. Setup mode stays
+ mounted meanwhile, so its first-call screen does not close until the scene takes it over. */}
+ <div className="flex justify-center my-20">
+ <Spinner className="text-2xl" />
+ </div>
+ <MCPSetupMode />
+ </>
+ )}
+ </OnboardingStep>
+ )
+}
+
export const mcpAnalyticsOnboarding: ProductOnboardingProvider = {
steps: (ctx) => [
{
@@ -44,7 +112,12 @@ export const mcpAnalyticsOnboarding: ProductOnboardingProvider = {
productKey: ProductKey.MCP_ANALYTICS,
stepKey: OnboardingStepKey.INSTALL,
role: ctx.role,
- render: () => <MCPAnalyticsInstallStep />,
+ render: () =>
+ ctx.featureFlags[FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE] ? (
+ <MCPAnalyticsSetupDoorStep />
+ ) : (
+ <MCPAnalyticsInstallStep />
+ ),
},
],
}