: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp-analytics): add setup mode state and logic behind a flag (#128669)
Lucas Faria80f480ddac72
diff --git a/frontend/src/lib/constants.tsx b/frontend/src/lib/constants.tsxindex 912247928585..340bc497db1e 100644--- a/frontend/src/lib/constants.tsx+++ b/frontend/src/lib/constants.tsx@@ -426,6 +426,7 @@ export const FEATURE_FLAGS = {MAX_WEB_ANALYTICS_NUDGE: 'posthog-ai-web-analytics-nudge', // owner: @jordanm-posthog #team-web-analyticsMCP_ANALYTICS_INTENT_ROUTING: 'mcp-analytics-intent-routing', // owner: #project-mcp-analyticsMCP_ANALYTICS_LEADERBOARD_HOME: 'mcp-analytics-leaderboard-home', // owner: #team-mcp-analytics, trial of the public leaderboard layout on the MCP analytics home tab+ MCP_ANALYTICS_SETUP_MODE: 'mcp-analytics-setup-mode', // owner: #team-mcp-analytics, the fullscreen setup walkthrough after a user picks an install routeMCP_GATEWAY: 'mcp-gateway', // owner: #team-context-mcp — gates the MCP gateway UI AND backend enforcement of built-in agent MCP access (delegated-only installs + restricted sandbox token scope); roll out by organizationMEMBER_BILLING_USAGE_SPEND_READ_ACCESS: 'member-billing-usage-spend-read-access', // owner: @pawelcebula #team-billing, grants members read-only access to billing usage/spend tabs; owner-only-billing takes precedenceMESSAGING_SES: 'messaging-ses', // owner #team-workflowsdiff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 0537e99d89c6..61cab02fcee3 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -4395,6 +4395,9 @@ importers:kea-router:specifier: 'catalog:'version: 3.4.2([email protected](patch_hash=139b8d1f1304f9d9da452a9a1244c94ea679dbcb85687d8999563146879fb6f5)([email protected]))+ kea-subscriptions:+ specifier: 'catalog:'+ version: 3.0.1([email protected](patch_hash=139b8d1f1304f9d9da452a9a1244c94ea679dbcb85687d8999563146879fb6f5)([email protected]))posthog-js:specifier: 'catalog:'version: 1.446.0(@types/[email protected])([email protected])diff --git a/products/mcp_analytics/backend/facade/api.py b/products/mcp_analytics/backend/facade/api.pyindex 2f94b0b03f38..895d8ee1d202 100644--- a/products/mcp_analytics/backend/facade/api.py+++ b/products/mcp_analytics/backend/facade/api.py@@ -178,16 +178,18 @@ def get_activity_overview(properties: list[AnyPropertyFilterDiscriminated] | None = None,filter_test_accounts: bool = False,user: User | None = None,+ refresh: bool = False,) -> contracts.ActivityOverview:"""Compute the activity view's aggregates and recent-call feed in one pass.Bounded to the last 30 days. Cached by the filters and the caller's property restrictions:for 5 minutes without restrictions, for less than one poll interval with them.+ ``refresh`` skips a cached entry older than a few seconds and stores the fresh result in its place.``properties`` and ``filter_test_accounts`` are the tabs' shared filters."""return logic.get_activity_overview(- team, properties=properties, filter_test_accounts=filter_test_accounts, user=user+ team, properties=properties, filter_test_accounts=filter_test_accounts, user=user, refresh=refresh)diff --git a/products/mcp_analytics/backend/logic.py b/products/mcp_analytics/backend/logic.pyindex 53b6715cb92c..4480d4e0ac04 100644--- a/products/mcp_analytics/backend/logic.py+++ b/products/mcp_analytics/backend/logic.py@@ -123,6 +123,9 @@ SESSIONS_CACHE_TTL_SECONDS = 30# empty overviews skip the cache, so a new team still sees its first call on the next poll.ACTIVITY_OVERVIEW_CACHE_TTL_SECONDS = 20UNRESTRICTED_ACTIVITY_OVERVIEW_CACHE_TTL_SECONDS = 5 * 60+# Setup mode polls with a refresh, and anyone signed in can send one, so a cached entry recomputes+# at most once in this window. A concurrent refresh gets the cached entry instead of a second run.+ACTIVITY_OVERVIEW_REFRESH_COOLDOWN_SECONDS = 5# One row per $session_id, aggregated straight from events. The column shape# (min/max/count/groupUniqArray/argMax) maps 1:1 onto a future AggregatingMergeTree@@ -732,6 +735,7 @@ def get_activity_overview(properties: list[AnyPropertyFilterDiscriminated] | None = None,filter_test_accounts: bool = False,user: User | None = None,+ refresh: bool = False,) -> contracts.ActivityOverview:"""Return everything the activity view renders, bounded to ``ACTIVITY_WINDOW``.@@ -740,8 +744,11 @@ def get_activity_overview("""restrictions = get_restricted_properties_with_group_type_index_for_team(user=user, team_id=team.pk)cache_key = _activity_overview_cache_key(team, properties, filter_test_accounts, restrictions, user)+ refresh_cooldown_key = f"{cache_key}_refresh_cooldown"cached = cache.get(cache_key)- if cached is not None:+ if cached is not None and not (+ refresh and cache.add(refresh_cooldown_key, True, ACTIVITY_OVERVIEW_REFRESH_COOLDOWN_SECONDS)+ ):return cachedoverview = _query_activity_overview(team, properties, filter_test_accounts, user)@@ -749,6 +756,7 @@ def get_activity_overview(if overview.stats.total_calls:ttl = ACTIVITY_OVERVIEW_CACHE_TTL_SECONDS if restrictions else UNRESTRICTED_ACTIVITY_OVERVIEW_CACHE_TTL_SECONDScache.set(cache_key, overview, ttl)+ cache.set(refresh_cooldown_key, True, ACTIVITY_OVERVIEW_REFRESH_COOLDOWN_SECONDS)return overviewdiff --git a/products/mcp_analytics/backend/presentation/serializers.py b/products/mcp_analytics/backend/presentation/serializers.pyindex f224347cfb46..2493e4fefcac 100644--- a/products/mcp_analytics/backend/presentation/serializers.py+++ b/products/mcp_analytics/backend/presentation/serializers.py@@ -513,6 +513,11 @@ class MCPActivityOverviewQuerySerializer(serializers.Serializer):default=False,help_text=FILTER_TEST_ACCOUNTS_HELP_TEXT,)+ refresh = serializers.BooleanField(+ required=False,+ default=False,+ help_text="Compute the overview again instead of serving the cached result, at most once every 5 seconds. The fresh result replaces the cached one.",+ )class MCPActivityOverviewSerializer(serializers.Serializer):diff --git a/products/mcp_analytics/backend/presentation/views.py b/products/mcp_analytics/backend/presentation/views.pyindex b212f4fc1df0..506a19876668 100644--- a/products/mcp_analytics/backend/presentation/views.py+++ b/products/mcp_analytics/backend/presentation/views.py@@ -316,7 +316,8 @@ class MCPSessionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):description=("Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, ""computed in one request. Powers the dashboard's activity view. Results are cached for up to 5 minutes, "- "or 20 seconds when the caller has property restrictions. An empty result is never cached."+ "or 20 seconds when the caller has property restrictions. An empty result is never cached. "+ "Pass refresh to skip the cache."),)@action(detail=False, methods=["get"], url_path="activity_overview", pagination_class=None)@@ -327,6 +328,7 @@ class MCPSessionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):properties=params["properties"],filter_test_accounts=params["filter_test_accounts"],user=cast(User, request.user),+ refresh=params["refresh"],)return Response(MCPActivityOverviewSerializer(overview).data)diff --git a/products/mcp_analytics/backend/tests/test_api.py b/products/mcp_analytics/backend/tests/test_api.pyindex 6a6af850ca11..a4fbfa1226ef 100644--- a/products/mcp_analytics/backend/tests/test_api.py+++ b/products/mcp_analytics/backend/tests/test_api.py@@ -910,12 +910,14 @@ class TestActivityOverview(_MCPAnalyticsTeamScopedTestMixin, ClickhouseTestMixin@parameterized.expand([- ("same_request_is_served_from_cache", 1, False, "never", 0, 1),- ("empty_result_is_not_cached", 0, False, "never", 0, 2),- ("other_filters_query_again", 1, True, "never", 0, 2),- ("other_property_restrictions_query_again", 1, False, "between_requests", 0, 2),- ("unrestricted_entry_outlives_a_poll_interval", 1, False, "never", 61, 1),- ("restricted_entry_expires_before_the_next_poll", 1, False, "before_requests", 21, 2),+ ("same_request_is_served_from_cache", 1, False, "never", 0, False, 1),+ ("empty_result_is_not_cached", 0, False, "never", 0, False, 2),+ ("other_filters_query_again", 1, True, "never", 0, False, 2),+ ("other_property_restrictions_query_again", 1, False, "between_requests", 0, False, 2),+ ("unrestricted_entry_outlives_a_poll_interval", 1, False, "never", 61, False, 1),+ ("restricted_entry_expires_before_the_next_poll", 1, False, "before_requests", 21, False, 2),+ ("refresh_within_the_cooldown_is_served_from_cache", 1, False, "never", 0, True, 1),+ ("refresh_after_the_cooldown_skips_the_cache", 1, False, "never", 6, True, 2),])def test_caches_overview_per_filters_and_property_restrictions(@@ -925,6 +927,7 @@ class TestActivityOverview(_MCPAnalyticsTeamScopedTestMixin, ClickhouseTestMixinchange_filters: bool,restrict_a_property: Literal["never", "before_requests", "between_requests"],seconds_later: int,+ refresh: bool,expected_calls: int,) -> None:self.team.test_account_filters = TEST_ACCOUNT_FILTERS@@ -938,7 +941,9 @@ class TestActivityOverview(_MCPAnalyticsTeamScopedTestMixin, ClickhouseTestMixinif restrict_a_property == "between_requests":self._restrict_a_property()with time_machine.travel(datetime.now(tz=UTC) + timedelta(seconds=seconds_later), tick=False):- overview = api.get_activity_overview(self.team, filter_test_accounts=change_filters, user=self.user)+ overview = api.get_activity_overview(+ self.team, filter_test_accounts=change_filters, user=self.user, refresh=refresh+ )assert overview.stats.total_calls == expected_callsdiff --git a/products/mcp_analytics/frontend/generated/api.schemas.ts b/products/mcp_analytics/frontend/generated/api.schemas.tsindex b2a8ab7fe2bd..e40efd791117 100644--- a/products/mcp_analytics/frontend/generated/api.schemas.ts+++ b/products/mcp_analytics/frontend/generated/api.schemas.ts@@ -772,4 +772,8 @@ export type McpAnalyticsSessionsActivityOverviewParams = {* Property filters that narrow the underlying $mcp_tool_call events, JSON-encoded. A list of event, person, or session property filters, each with key, value, operator, and type. Example: [{"key": "$mcp_tool_name", "value": ["query_run"], "operator": "exact", "type": "event"}]*/properties?: string+ /**+ * Compute the overview again instead of serving the cached result, at most once every 5 seconds. The fresh result replaces the cached one.+ */+ refresh?: boolean}diff --git a/products/mcp_analytics/frontend/generated/api.ts b/products/mcp_analytics/frontend/generated/api.tsindex d294efc045ab..d0617b934726 100644--- a/products/mcp_analytics/frontend/generated/api.ts+++ b/products/mcp_analytics/frontend/generated/api.ts@@ -304,7 +304,7 @@ export const getMcpAnalyticsSessionsActivityOverviewUrl = (}/**- * Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, computed in one request. Powers the dashboard's activity view. Results are cached for up to 5 minutes, or 20 seconds when the caller has property restrictions. An empty result is never cached.+ * Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, computed in one request. Powers the dashboard's activity view. Results are cached for up to 5 minutes, or 20 seconds when the caller has property restrictions. An empty result is never cached. Pass refresh to skip the cache.*/export const mcpAnalyticsSessionsActivityOverview = async (projectId: string,diff --git a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.tsindex ed43ce6bc585..c574ef2c4ede 100644--- a/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts+++ b/products/mcp_analytics/frontend/mcpAnalyticsOnboardingLogic.ts@@ -258,7 +258,7 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(}},})),- afterMount(({ actions, cache }) => {+ afterMount(({ actions, cache, values }) => {actions.loadSignals()// Register product intent so activation lands in the standard cross-customer// funnel (`has_activated_mcp_analytics` flips once tool calls arrive too).@@ -269,7 +269,9 @@ export const mcpAnalyticsOnboardingLogic = kea<mcpAnalyticsOnboardingLogicType>(})}cache.disposables.add(() => {- const id = window.setInterval(() => actions.loadSignals(), POLL_INTERVAL_MS)+ // Skips while a request is in flight, so a request slower than the interval is not+ // cancelled by the next one. Setup mode polls the same loader on its own timer.+ const id = window.setInterval(() => !values.signalsLoading && actions.loadSignals(), POLL_INTERVAL_MS)return () => clearInterval(id)}, 'poll')}),diff --git a/products/mcp_analytics/frontend/setupMode/callClient.ts b/products/mcp_analytics/frontend/setupMode/callClient.tsnew file mode 100644index 000000000000..b80f6b6f5c10--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/callClient.ts@@ -0,0 +1,6 @@+import type { MCPActivityRecentCallApi } from '../generated/api.schemas'++/** The name a call's client goes by, with the label `harnessMark` gives its own mark. */+export function callClientLabel(call: MCPActivityRecentCallApi): string {+ return call.client_name || 'Unidentified client'+}diff --git a/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.test.ts b/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.test.tsnew file mode 100644index 000000000000..ce22b629ca99--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.test.ts@@ -0,0 +1,262 @@+import { MOCK_TEAM_ID } from 'lib/api.mock'++import { router } from 'kea-router'+import { expectLogic } from 'kea-test-utils'++import api from 'lib/api'+import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'+import { FEATURE_FLAGS } from 'lib/constants'+import { featureFlagLogic } from 'lib/logic/featureFlagLogic'+import posthog from 'lib/posthog-typed'+import { removeProjectIdIfPresent } from 'lib/utils/kea-router'+import { urls } from 'scenes/urls'++import { sidePanelStateLogic } from '~/layout/navigation-3000/sidepanel/sidePanelStateLogic'+import { ProductKey } from '~/queries/schema/schema-general'+import { initKeaTests } from '~/test/init'+import { SidePanelTab } from '~/types'++import { mcpAnalyticsSessionsActivityOverview } from '../generated/api'+import { mcpSetupModeLogic, resetSetupModeTrackingForTests } from './mcpSetupModeLogic'++jest.mock('lib/api')+jest.mock('../generated/api', () => ({+ ...jest.requireActual('../generated/api'),+ mcpAnalyticsSessionsActivityOverview: jest.fn(),+}))+jest.mock('lib/posthog-typed', () => ({ __esModule: true, default: { capture: jest.fn(), captureRaw: jest.fn() } }))++const captureRawMock = posthog.captureRaw as jest.Mock++// Signal row shape: [has_initialize, tool_calls_total, tool_calls_7d, first_call_at]+const NOT_INSTRUMENTED = [0, 0, 0, '1970-01-01T00:00:00Z']+const CONNECTED = [1, 0, 0, '1970-01-01T00:00:00Z']+const ONE_CALL = [1, 1, 1, '2026-07-01T00:00:00Z']++describe('mcpSetupModeLogic', () => {+ let logic: ReturnType<typeof mcpSetupModeLogic.build>++ function enableSetupMode(enabled: boolean): void {+ featureFlagLogic.actions.setFeatureFlags([], { [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]: enabled })+ }++ beforeEach(() => {+ jest.clearAllMocks()+ initKeaTests()+ resetSetupModeTrackingForTests()+ jest.spyOn(api, 'query').mockResolvedValue({ results: [NOT_INSTRUMENTED] } as any)+ router.actions.push(urls.mcpAnalyticsDashboard(), { landing: 'auto' })+ logic = mcpSetupModeLogic()+ logic.mount()+ })++ afterEach(() => {+ logic.unmount()+ })++ it.each([+ { action: 'wizard command copied', route: 'wizard', expected: 'wizard', trigger: 'wizard_copy' },+ { action: 'agent prompt copied', route: 'agent', expected: 'agent', trigger: 'agent_copy' },+ ] as const)('opens the $expected path when the empty state reports "$action"', async (testCase) => {+ enableSetupMode(true)++ productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }).actions.reportSetupInteraction(+ testCase.action,+ 'needs-setup',+ testCase.route+ )+ await expectLogic(logic).toFinishAllListeners()++ expect(router.values.searchParams).toEqual({ landing: 'auto', setup: testCase.expected })+ expect(logic.values.setupPath).toBe(testCase.expected)+ expect(captureRawMock).toHaveBeenCalledWith('mcp analytics setup mode opened', {+ path: testCase.expected,+ trigger: testCase.trigger,+ })+ })++ it.each([+ { name: 'the flag is off', enabled: false, action: 'wizard command copied', preview: false },+ { name: 'the interaction is not a copy', enabled: true, action: 'docs clicked', preview: false },+ { name: 'the screen is a preview', enabled: true, action: 'wizard command copied', preview: true },+ ])('stays closed when $name', async (testCase) => {+ enableSetupMode(testCase.enabled)++ productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }).actions.reportSetupInteraction(+ testCase.action,+ 'needs-setup',+ 'wizard',+ testCase.preview+ )+ await expectLogic(logic).toFinishAllListeners()++ expect(router.values.searchParams).toEqual({ landing: 'auto' })+ expect(logic.values.setupPath).toBe(null)+ })++ it.each([+ { reason: 'back', expectedPath: urls.mcpAnalyticsDashboard() },+ { reason: 'escape', expectedPath: urls.mcpAnalyticsDashboard() },+ { reason: 'finished', expectedPath: urls.mcpAnalyticsActivity() },+ ] as const)('exit with $reason removes the setup params and lands on $expectedPath', async (testCase) => {+ enableSetupMode(true)+ router.actions.push(urls.mcpAnalyticsDashboard(), { landing: 'auto', setup: 'agent', setup_step: 'useful' })+ await expectLogic(logic).toFinishAllListeners()++ logic.actions.exitSetupMode(testCase.reason)+ await expectLogic(logic).toFinishAllListeners()++ expect(router.values.location.pathname).toBe(`/project/${MOCK_TEAM_ID}${testCase.expectedPath}`)+ expect(router.values.searchParams).toEqual({ landing: 'auto' })+ expect(logic.values.setupPath).toBe(null)+ expect(captureRawMock).toHaveBeenCalledWith('mcp analytics setup mode exited', {+ path: 'agent',+ step: 'connect',+ reason: testCase.reason,+ })+ })++ it('asking PostHog AI closes setup mode before opening the side panel with the question', async () => {+ enableSetupMode(true)+ sidePanelStateLogic.mount()+ router.actions.push(urls.mcpAnalyticsDashboard(), { setup: 'agent', setup_step: 'useful' })+ await expectLogic(logic).toFinishAllListeners()++ logic.actions.askPostHogAI('What can MCP analytics tell me?')+ await expectLogic(logic).toFinishAllListeners()++ expect(logic.values.isOpen).toBe(false)+ expect(router.values.location.pathname).toBe(`/project/${MOCK_TEAM_ID}${urls.mcpAnalyticsActivity()}`)+ expect(sidePanelStateLogic.values.selectedTab).toBe(SidePanelTab.Max)+ expect(sidePanelStateLogic.values.selectedTabOptions).toBe('!What can MCP analytics tell me?')+ expect(captureRawMock).toHaveBeenCalledWith('mcp analytics setup mode exited', {+ path: 'agent',+ step: 'connect',+ reason: 'ask_ai',+ })+ })++ it.each([+ { page: 'the welcome page', path: urls.onboardingWelcome(), expectedPath: urls.mcpAnalytics() },+ // The onboarding step completes onboarding and redirects itself.+ {+ page: 'the onboarding install step',+ path: '/onboarding/mcp_analytics',+ expectedPath: '/onboarding/mcp_analytics',+ },+ { page: 'the scene', path: urls.mcpAnalyticsDashboard(), expectedPath: urls.mcpAnalyticsDashboard() },+ ])('keeps the first-call reveal open when the first call lands on $page', async (testCase) => {+ enableSetupMode(true)+ router.actions.push(testCase.path, { setup: 'agent' })+ await expectLogic(logic).toFinishAllListeners()+ jest.spyOn(api, 'query').mockResolvedValue({ results: [ONE_CALL] } as any)++ logic.actions.loadSignals()+ await expectLogic(logic).toFinishAllListeners()++ expect(removeProjectIdIfPresent(router.values.location.pathname)).toBe(testCase.expectedPath)+ expect(router.values.searchParams).toMatchObject({ setup: 'agent' })+ })++ it('reports a close by navigation as an exit and tracks the next open in full', async () => {+ enableSetupMode(true)+ const copyWizardCommand = (): void =>+ productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }).actions.reportSetupInteraction(+ 'wizard command copied',+ 'needs-setup',+ 'wizard'+ )+ copyWizardCommand()+ await expectLogic(logic).toFinishAllListeners()++ router.actions.push(urls.mcpAnalyticsDashboard())+ await expectLogic(logic).toFinishAllListeners()+ copyWizardCommand()+ await expectLogic(logic).toFinishAllListeners()++ const events = captureRawMock.mock.calls.map(([event, properties]) => [event, properties])+ expect(events).toEqual([+ ['mcp analytics setup mode opened', { path: 'wizard', trigger: 'wizard_copy' }],+ ['mcp analytics setup mode step viewed', { path: 'wizard', step: 'connect' }],+ ['mcp analytics setup mode exited', { path: 'wizard', step: 'connect', reason: 'navigated' }],+ ['mcp analytics setup mode opened', { path: 'wizard', trigger: 'wizard_copy' }],+ ['mcp analytics setup mode step viewed', { path: 'wizard', step: 'connect' }],+ ])+ })++ describe('polling while setup mode connects', () => {+ beforeEach(() => {+ jest.useFakeTimers({ doNotFake: ['nextTick', 'queueMicrotask', 'setImmediate'] })+ // Mounted again under fake timers, so the onboarding logic's own poll runs here too.+ logic.unmount()+ logic = mcpSetupModeLogic()+ logic.mount()+ })+ afterEach(() => {+ jest.useRealTimers()+ })++ async function openAgentSetup(): Promise<void> {+ enableSetupMode(true)+ router.actions.push(urls.mcpAnalyticsDashboard(), { setup: 'agent' })+ await jest.advanceTimersByTimeAsync(0)+ }++ it.each([+ { poll: 'signals', signals: CONNECTED, step: 'connect' },+ { poll: 'recent calls', signals: ONE_CALL, step: 'first-call' },+ ])(+ 'waits for a slow $poll query instead of cancelling it with the next poll',+ async ({ poll, signals, step }) => {+ const query = jest+ .spyOn(api, 'query')+ .mockReset()+ .mockResolvedValueOnce({ results: [signals] } as any)+ const overview = jest.mocked(mcpAnalyticsSessionsActivityOverview).mockReset()+ logic.actions.loadSignals()+ await jest.advanceTimersByTimeAsync(0)+ await openAgentSetup()+ expect(logic.values.step).toBe(step)+ const slowRequest = poll === 'signals' ? query : overview+ slowRequest.mockReturnValue(new Promise(() => {}))+ const sentBefore = slowRequest.mock.calls.length++ await jest.advanceTimersByTimeAsync(31000)++ expect(slowRequest.mock.calls.length - sentBefore).toBe(1)+ }+ )++ it('retries soon when the first signals query fails, instead of spinning until the slow poll', async () => {+ logic.unmount()+ initKeaTests()+ const query = jest.spyOn(api, 'query').mockRejectedValueOnce(new Error('query failed'))+ logic = mcpSetupModeLogic()+ logic.mount()+ await jest.advanceTimersByTimeAsync(0)+ await openAgentSetup()+ expect(logic.values.step).toBeNull()+ query.mockResolvedValue({ results: [CONNECTED] } as any)++ await jest.advanceTimersByTimeAsync(6000)++ expect(logic.values.step).toBe('connect')+ })+ })++ it('exits on Escape wherever focus is', async () => {+ enableSetupMode(true)+ router.actions.push(urls.mcpAnalyticsDashboard(), { setup: 'wizard' })+ await expectLogic(logic).toFinishAllListeners()++ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))+ await expectLogic(logic).toFinishAllListeners()++ expect(router.values.searchParams).toEqual({})+ expect(captureRawMock).toHaveBeenCalledWith('mcp analytics setup mode exited', {+ path: 'wizard',+ step: 'connect',+ reason: 'escape',+ })+ })+})diff --git a/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.ts b/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.tsnew file mode 100644index 000000000000..8328ccf53ff1--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/mcpSetupModeLogic.ts@@ -0,0 +1,407 @@+import { MakeLogicType, actions, connect, kea, listeners, path, reducers, selectors } from 'kea'+import { loaders } from 'kea-loaders'+import { router } from 'kea-router'+import { subscriptions } from 'kea-subscriptions'++import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'+import { FEATURE_FLAGS } from 'lib/constants'+import { featureFlagLogic } from 'lib/logic/featureFlagLogic'+import posthog from 'lib/posthog-typed'+import { removeProjectIdIfPresent } from 'lib/utils/kea-router'+import { autoRunMaxPrompt } from 'scenes/max/maxPrompt'+import { teamLogic } from 'scenes/teamLogic'+import { urls } from 'scenes/urls'+import { userLogic } from 'scenes/userLogic'++import { sidePanelStateLogic } from '~/layout/navigation-3000/sidepanel/sidePanelStateLogic'+import { ProductKey } from '~/queries/schema/schema-general'+import { SidePanelTab } from '~/types'++import type { FeatureFlagsSet } from '../../../../frontend/src/lib/logic/featureFlagLogic'+import { mcpAnalyticsSessionsActivityOverview } from '../generated/api'+import type { MCPActivityRecentCallApi } from '../generated/api.schemas'+import { mcpAnalyticsOnboardingLogic } from '../mcpAnalyticsOnboardingLogic'+import type { MCPOnboardingSignals, MCPOnboardingState } from '../mcpAnalyticsOnboardingLogic'+import {+ type MCPSetupExitReason,+ type MCPSetupPath,+ type MCPSetupStep,+ type MCPSetupTrigger,+ SETUP_PARAM,+ SETUP_STEP_PARAM,+ connectStateFor,+ parseSetupPath,+ setupStepFor,+} from './setupMode'+import type { MCPConnectState } from './setupMode'++/** The two calls the reveal shows as cards, plus the newer ones its calls panel lists beside them. */+const RECENT_CALLS = 7++// Faster than the onboarding logic's own poll: someone in setup mode is watching for the moment+// their server answers. Both queries stay cheap while the project has a handful of events.+const CONNECT_POLL_MS = 5000+const FIRST_CALL_POLL_MS = 10000++// The gate swaps the empty state for the scene when the first call lands, which remounts this+// logic, and a reload remounts it too. Module scope keeps "opened" and "step viewed" to one event+// per real change across those remounts, the way the wizard-sync telemetry guards do.+const tracking = {+ opened: false,+ lastViewedStep: null as string | null,+ // What an exit event reports when setup mode closes through the URL, after its own params are gone.+ lastViewed: null as { path: MCPSetupPath | null; step: MCPSetupStep | null } | null,+}++function resetTracking(): void {+ tracking.opened = false+ tracking.lastViewedStep = null+ tracking.lastViewed = null+}++export function resetSetupModeTrackingForTests(): void {+ resetTracking()+}++/** What setup mode polls for while it is open: the signals until a call lands, then the calls themselves. */+type SetupPollTarget = 'signals' | 'calls' | null++function capture(event: string, properties: Record<string, unknown>): void {+ if (userLogic.findMounted()?.values.user?.is_impersonated) {+ return+ }+ posthog.captureRaw(event, properties)+}++function withoutSetupParams(searchParams: Record<string, any>): Record<string, any> {+ const { [SETUP_PARAM]: _path, [SETUP_STEP_PARAM]: _step, ...rest } = searchParams+ return rest+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface mcpSetupModeLogicValues {+ featureFlags: FeatureFlagsSet // featureFlagLogic+ onboardingState: MCPOnboardingState | null // mcpAnalyticsOnboardingLogic+ signals: MCPOnboardingSignals | null // mcpAnalyticsOnboardingLogic+ signalsLoading: boolean // mcpAnalyticsOnboardingLogic+ location: {+ pathname: string+ search: string+ hash: string+ } // router+ searchParams: Record<string, any> // router+ currentProjectId: number | string // teamLogic+ connectState: MCPConnectState+ isEnabled: boolean+ isOpen: boolean+ pollTarget: SetupPollTarget+ recentCalls: MCPActivityRecentCallApi[] | null+ recentCallsFailed: boolean+ recentCallsLoading: boolean+ setupPath: MCPSetupPath | null+ step: MCPSetupStep | null+ viewedStep: string | null+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface mcpSetupModeLogicActions {+ loadSignals: (_?: void | undefined) => void // mcpAnalyticsOnboardingLogic+ reportSetupInteraction: (+ action: string,+ mode: import('../../../../frontend/src/lib/components/ProductEmptyState/types').ProductEmptyStateMode,+ route?: null | import('lib/components/ProductEmptyState/productSetupStatusLogic').ProductSetupRoute | undefined,+ preview?: boolean | undefined,+ wizardSession?:+ | {+ phase: string+ session_id: string+ }+ | undefined+ ) => {+ action: string+ mode: import('../../../../frontend/src/lib/components/ProductEmptyState/types').ProductEmptyStateMode+ preview: boolean+ route: null | import('lib/components/ProductEmptyState/productSetupStatusLogic').ProductSetupRoute+ wizardSession:+ | {+ phase: string+ session_id: string+ }+ | undefined+ } // productSetupStatusLogic+ askPostHogAI: (prompt: string) => {+ prompt: string+ }+ exitSetupMode: (reason: MCPSetupExitReason) => {+ reason: MCPSetupExitReason+ }+ goToUsefulStep: () => {+ value: true+ }+ loadRecentCalls: (_: void) => void+ loadRecentCallsFailure: (+ error: string,+ errorObject?: any+ ) => {+ error: string+ errorObject?: any+ }+ loadRecentCallsSuccess: (+ recentCalls: MCPActivityRecentCallApi[] | null,+ payload?: void+ ) => {+ recentCalls: MCPActivityRecentCallApi[] | null+ payload?: void+ }+ openSetupMode: (+ path: MCPSetupPath,+ trigger: MCPSetupTrigger+ ) => {+ path: MCPSetupPath+ trigger: MCPSetupTrigger+ }+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface mcpSetupModeLogicMeta {+ __keaTypeGenInternalSelectorTypes: {+ isEnabled: (featureFlags: FeatureFlagsSet) => boolean+ setupPath: (isEnabled: boolean, searchParams: Record<string, any>) => MCPSetupPath | null+ isOpen: (setupPath: MCPSetupPath | null) => boolean+ step: (+ setupPath: MCPSetupPath | null,+ signals: MCPOnboardingSignals | null,+ searchParams: Record<string, any>+ ) => MCPSetupStep | null+ viewedStep: (setupPath: MCPSetupPath | null, step: MCPSetupStep | null) => string | null+ connectState: (onboardingState: MCPOnboardingState | null) => MCPConnectState+ pollTarget: (isOpen: boolean, step: MCPSetupStep | null) => SetupPollTarget+ }+}++export type mcpSetupModeLogicType = MakeLogicType<+ mcpSetupModeLogicValues,+ mcpSetupModeLogicActions,+ Record<string, any>,+ mcpSetupModeLogicMeta+>++export const mcpSetupModeLogic = kea<mcpSetupModeLogicType>([+ path(['products', 'mcp_analytics', 'frontend', 'setupMode', 'mcpSetupModeLogic']),+ connect(() => ({+ values: [+ router,+ ['searchParams', 'location'],+ featureFlagLogic,+ ['featureFlags'],+ mcpAnalyticsOnboardingLogic,+ ['signals', 'signalsLoading', 'onboardingState'],+ teamLogic,+ ['currentProjectId'],+ ],+ actions: [+ productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }),+ ['reportSetupInteraction'],+ mcpAnalyticsOnboardingLogic,+ ['loadSignals'],+ ],+ })),+ actions({+ openSetupMode: (path: MCPSetupPath, trigger: MCPSetupTrigger) => ({ path, trigger }),+ goToUsefulStep: true,+ exitSetupMode: (reason: MCPSetupExitReason) => ({ reason }),+ askPostHogAI: (prompt: string) => ({ prompt }),+ }),+ loaders(({ values }) => ({+ recentCalls: [+ null as MCPActivityRecentCallApi[] | null,+ {+ loadRecentCalls: async (_: void, breakpoint): Promise<MCPActivityRecentCallApi[] | null> => {+ // The overview resolves each call's client to a harness label and pulls the readable+ // message out of a failed call's response, both of which only the backend knows how to do.+ // `refresh` skips the overview's shared five-minute cache, which would hide the calls that follow the first.+ const overview = await mcpAnalyticsSessionsActivityOverview(String(values.currentProjectId), {+ refresh: true,+ })+ breakpoint()+ return overview.recent_calls.slice(0, RECENT_CALLS)+ },+ },+ ],+ })),+ reducers({+ recentCallsFailed: [+ false,+ {+ loadRecentCallsSuccess: () => false,+ loadRecentCallsFailure: () => true,+ },+ ],+ }),+ selectors({+ isEnabled: [+ (s) => [s.featureFlags],+ (featureFlags: Record<string, unknown>): boolean => !!featureFlags[FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE],+ ],+ setupPath: [+ (s) => [s.isEnabled, s.searchParams],+ (isEnabled: boolean, searchParams: Record<string, unknown>): MCPSetupPath | null =>+ isEnabled ? parseSetupPath(searchParams[SETUP_PARAM]) : null,+ ],+ isOpen: [(s) => [s.setupPath], (setupPath: MCPSetupPath | null): boolean => setupPath !== null],+ /** `null` until the onboarding signals answer, so a reload never flashes the wrong step. */+ step: [+ (s) => [s.setupPath, s.signals, s.searchParams],+ (+ setupPath: MCPSetupPath | null,+ signals: { hasToolCall: boolean } | null,+ searchParams: Record<string, unknown>+ ): MCPSetupStep | null => {+ if (!setupPath || !signals) {+ return null+ }+ const requested = searchParams[SETUP_STEP_PARAM]+ return setupStepFor({+ hasToolCall: signals.hasToolCall,+ requestedStep: typeof requested === 'string' ? requested : null,+ })+ },+ ],+ viewedStep: [+ (s) => [s.setupPath, s.step],+ (setupPath: MCPSetupPath | null, step: MCPSetupStep | null): string | null =>+ setupPath && step ? `${setupPath}:${step}` : null,+ ],+ connectState: [+ (s) => [s.onboardingState],+ (onboardingState: MCPOnboardingState | null): MCPConnectState => connectStateFor(onboardingState),+ ],+ // An unknown step (the first signals query failed) polls the signals too, so a retry comes quickly.+ pollTarget: [+ (s) => [s.isOpen, s.step],+ (isOpen: boolean, step: MCPSetupStep | null): SetupPollTarget =>+ !isOpen+ ? null+ : step === null || step === 'connect'+ ? 'signals'+ : step === 'first-call'+ ? 'calls'+ : null,+ ],+ }),+ listeners(({ actions, values }) => ({+ reportSetupInteraction: ({ action, preview }) => {+ if (preview) {+ return+ }+ if (action === 'wizard command copied') {+ actions.openSetupMode('wizard', 'wizard_copy')+ } else if (action === 'agent prompt copied') {+ actions.openSetupMode('agent', 'agent_copy')+ }+ },+ openSetupMode: ({ path, trigger }) => {+ if (!values.isEnabled || values.isOpen) {+ return+ }+ tracking.opened = true+ capture('mcp analytics setup mode opened', { path, trigger })+ router.actions.push(values.location.pathname, {+ ...withoutSetupParams(values.searchParams),+ [SETUP_PARAM]: path,+ })+ },+ askPostHogAI: ({ prompt }) => {+ // The side panel opens under the fullscreen setup mode, so close setup mode first.+ actions.exitSetupMode('ask_ai')+ sidePanelStateLogic.actions.openSidePanel(SidePanelTab.Max, autoRunMaxPrompt(prompt))+ },+ goToUsefulStep: () => {+ router.actions.replace(values.location.pathname, { ...values.searchParams, [SETUP_STEP_PARAM]: 'useful' })+ },+ exitSetupMode: ({ reason }) => {+ if (!values.isOpen) {+ return+ }+ capture('mcp analytics setup mode exited', { path: values.setupPath, step: values.step, reason })+ resetTracking()+ const searchParams = withoutSetupParams(values.searchParams)+ if (reason === 'finished' || reason === 'ask_ai') {+ router.actions.push(urls.mcpAnalyticsActivity(), searchParams)+ } else {+ router.actions.replace(values.location.pathname, searchParams)+ }+ },+ })),+ subscriptions(({ actions, values, cache }) => ({+ isOpen: (isOpen: boolean) => {+ // On the window rather than the modal, because the modal only hears keys while focus is inside+ // it, and a step change replaces the focused button.+ if (isOpen) {+ cache.disposables.add(() => {+ const onKeyDown = (event: KeyboardEvent): void => {+ if (event.key === 'Escape' && !event.defaultPrevented) {+ actions.exitSetupMode('escape')+ }+ }+ window.addEventListener('keydown', onKeyDown)+ return () => window.removeEventListener('keydown', onKeyDown)+ }, 'escape')+ } else {+ cache.disposables.dispose('escape')+ // Still marked open means it closed without `exitSetupMode`: browser history or a link out.+ if (tracking.opened) {+ capture('mcp analytics setup mode exited', { ...tracking.lastViewed, reason: 'navigated' })+ resetTracking()+ }+ }+ // Anything that opens setup mode without `openSetupMode` came in through the URL: a reload,+ // a shared link, or browser history.+ if (isOpen && !tracking.opened) {+ tracking.opened = true+ capture('mcp analytics setup mode opened', { path: values.setupPath, trigger: 'url' })+ }+ },+ step: (step: MCPSetupStep | null) => {+ if (step === 'first-call') {+ // Only the scene keeps a setup mode host once the product has data, so on the welcome page the+ // reveal would unmount with the empty state. The onboarding step redirects itself, because it must+ // complete onboarding first.+ const path = removeProjectIdIfPresent(values.location.pathname)+ if (!path.startsWith(urls.mcpAnalytics()) && !path.startsWith(urls.onboarding())) {+ router.actions.replace(urls.mcpAnalytics(), values.searchParams)+ }+ }+ },+ pollTarget: (pollTarget: SetupPollTarget) => {+ cache.disposables.dispose('setupPoll')+ // Each poll skips while the last request is in flight. A request slower than the interval+ // would otherwise be cancelled by the next one, forever.+ if (pollTarget === 'signals') {+ cache.disposables.add(() => {+ const id = window.setInterval(+ () => !values.signalsLoading && actions.loadSignals(),+ CONNECT_POLL_MS+ )+ return () => clearInterval(id)+ }, 'setupPoll')+ } else if (pollTarget === 'calls') {+ actions.loadRecentCalls()+ cache.disposables.add(() => {+ const id = window.setInterval(+ () => !values.recentCallsLoading && actions.loadRecentCalls(),+ FIRST_CALL_POLL_MS+ )+ return () => clearInterval(id)+ }, 'setupPoll')+ }+ },+ viewedStep: (viewedStep: string | null) => {+ if (viewedStep && viewedStep !== tracking.lastViewedStep) {+ tracking.lastViewedStep = viewedStep+ tracking.lastViewed = { path: values.setupPath, step: values.step }+ capture('mcp analytics setup mode step viewed', { step: values.step, path: values.setupPath })+ }+ },+ })),+])diff --git a/products/mcp_analytics/frontend/setupMode/setupMode.test.ts b/products/mcp_analytics/frontend/setupMode/setupMode.test.tsnew file mode 100644index 000000000000..5ac717b19e61--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/setupMode.test.ts@@ -0,0 +1,35 @@+import { connectStateFor, parseSetupPath, setupStepFor } from './setupMode'++describe('setupMode', () => {+ it.each([+ { hasToolCall: false, requestedStep: null, expected: 'connect' },+ { hasToolCall: false, requestedStep: 'useful', expected: 'connect' },+ { hasToolCall: true, requestedStep: null, expected: 'first-call' },+ { hasToolCall: true, requestedStep: 'connect', expected: 'first-call' },+ { hasToolCall: true, requestedStep: 'useful', expected: 'useful' },+ ] as const)(+ 'tool call $hasToolCall and requested step $requestedStep resolve to $expected',+ ({ hasToolCall, requestedStep, expected }) => {+ expect(setupStepFor({ hasToolCall, requestedStep })).toBe(expected)+ }+ )++ it.each([+ { onboardingState: null, expected: 'waiting' },+ { onboardingState: 'not-instrumented', expected: 'waiting' },+ { onboardingState: 'connected-no-calls', expected: 'connected' },+ { onboardingState: 'onboarded', expected: 'connected' },+ ] as const)('onboarding state $onboardingState resolves to $expected', ({ onboardingState, expected }) => {+ expect(connectStateFor(onboardingState)).toEqual({ kind: expected })+ })++ it.each([+ { value: 'wizard', expected: 'wizard' },+ { value: 'agent', expected: 'agent' },+ { value: 'manual', expected: null },+ { value: undefined, expected: null },+ { value: 1, expected: null },+ ])('parses the setup param $value as $expected', ({ value, expected }) => {+ expect(parseSetupPath(value)).toBe(expected)+ })+})diff --git a/products/mcp_analytics/frontend/setupMode/setupMode.ts b/products/mcp_analytics/frontend/setupMode/setupMode.tsnew file mode 100644index 000000000000..18a707b63d88--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/setupMode.ts@@ -0,0 +1,45 @@+import type { MCPOnboardingState } from '../mcpAnalyticsOnboardingLogic'++/** The button that opened setup mode. Pinned: the `setup` URL param carries these values. */+export type MCPSetupPath = 'wizard' | 'agent'++export type MCPSetupStep = 'connect' | 'first-call' | 'useful'++export const MCP_SETUP_STEPS: MCPSetupStep[] = ['connect', 'first-call', 'useful']++// pinned: URL params, bookmarks and shared links depend on them+export const SETUP_PARAM = 'setup'+export const SETUP_STEP_PARAM = 'setup_step'++export type MCPSetupTrigger = 'wizard_copy' | 'agent_copy' | 'url'++export type MCPSetupExitReason = 'back' | 'escape' | 'finished' | 'ask_ai' | 'navigated'++export function parseSetupPath(value: unknown): MCPSetupPath | null {+ return value === 'wizard' || value === 'agent' ? value : null+}++/**+ * Only `useful` is stored in the URL. The other two steps follow the data: no tool call yet means+ * the user is still connecting, and the first call moves them on by itself.+ */+export function setupStepFor({+ hasToolCall,+ requestedStep,+}: {+ hasToolCall: boolean+ requestedStep: string | null+}): MCPSetupStep {+ if (!hasToolCall) {+ return 'connect'+ }+ return requestedStep === 'useful' ? 'useful' : 'first-call'+}++export type MCPConnectState = { kind: 'waiting' } | { kind: 'connected' }++export function connectStateFor(onboardingState: MCPOnboardingState | null): MCPConnectState {+ return onboardingState === 'connected-no-calls' || onboardingState === 'onboarded'+ ? { kind: 'connected' }+ : { kind: 'waiting' }+}diff --git a/products/mcp_analytics/package.json b/products/mcp_analytics/package.jsonindex da097b4980b4..adb5bd6a19c1 100644--- a/products/mcp_analytics/package.json+++ b/products/mcp_analytics/package.json@@ -12,6 +12,7 @@"kea": "catalog:","kea-loaders": "catalog:","kea-router": "catalog:",+ "kea-subscriptions": "catalog:","posthog-js": "catalog:","react-intersection-observer": "9.5.3"},diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 38c4ebb0bda7..509ed992781f 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -131428,6 +131428,10 @@ export namespace Schemas {* Property filters that narrow the underlying $mcp_tool_call events, JSON-encoded. A list of event, person, or session property filters, each with key, value, operator, and type. Example: [{"key": "$mcp_tool_name", "value": ["query_run"], "operator": "exact", "type": "event"}]*/properties?: string;+ /**+ * Compute the overview again instead of serving the cached result, at most once every 5 seconds. The fresh result replaces the cached one.+ */+ refresh?: boolean;};export type McpGatewayAuditListParams = {