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): open setup mode from the setup screen and the scene (#128681)

Lucas Faria015396078ed5
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index c8c70c832a50..1034dd06928b 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -14370,6 +14370,50 @@ snapshots:
hash: v1.k794b7964.1cc84f683757e63495ffa98459b9556442c3535018f4379e0e522a6bda285f4c.6ZS_Z7xaUDE5IW381cySLT26W5FmcdMyCK9qASAfATM
scenes-app-mcp-analytics-nudge-toast--default--light:
hash: v1.k794b7964.e7ac9b38fc3e2fdfdd1189c833ff16264f3807a5489fc1be778aa06be372538c.K4vqorVUJpvkp2t_j2mlWWbQwYG5wbaxGAUvetJbcrQ
+ scenes-app-mcp-analytics-setup-mode--connect--medium--dark:
+ hash: v1.k794b7964.90d47e1af584449d10a9a17c35dde80b053ef376450374b50330aceb9d7bac22.ZMQYh4GMn8Jn_YXTcvHE2F2mlrVT1ZOZ7GIYUnsEnNo
+ scenes-app-mcp-analytics-setup-mode--connect--medium--light:
+ hash: v1.k794b7964.0c1065dde14adde5a23247d38ceebc2df9b21c8e3ed1de298a49f5f7338272a9.IofGkc2Axk9qwJ1vj9Tph-R3DByQHnPZshLR7PbcJlU
+ scenes-app-mcp-analytics-setup-mode--connect--narrow--dark:
+ hash: v1.k794b7964.240a51c430567a8e6a2b83d56994e1929f3a1ca3641f2e24892fb1fb23c992b4.oMf7qtf0mPe2YUv2Nt01spY7LbVy0keSoxUaJ2eAIVc
+ 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
+ scenes-app-mcp-analytics-setup-mode--connected--light:
+ hash: v1.k794b7964.0d7807c3aab3147e4625e4d1cdb96b3988f5e806906112949b92a97bc8b66ee0.nLcykpqr6QAQlCBbDGa0fI81VvshoeMKyJ4lVnGooko
+ scenes-app-mcp-analytics-setup-mode--first-call-success--dark:
+ hash: v1.k794b7964.b3c4a6086bc050da09d1734126e80cad6e2ce5a07cafa65f6a31444515107f72.KCkOgR6TtNZxUY6A5WfaewEB1VTB5wN_cXfQ8jFuzYo
+ scenes-app-mcp-analytics-setup-mode--first-call-success--light:
+ hash: v1.k794b7964.693ef1fdbadcd4c88ba9b83e806ebe37d9da5cbd07a69e0f88704eabf54166c5.MsHx6YLPGzSsx9_8SWaPWyBT5cROOYJCU7CrzaEX7TM
+ scenes-app-mcp-analytics-setup-mode--first-call-with-failure--medium--dark:
+ hash: v1.k794b7964.e54a7bde5d6e1b6729345a02f1570fca6ddd6019cce60e9c6b6a9470a88dbb11.n2eu8ttHO1rM7FsN8zPvHSU8J8vuKQKy9iWayTlUdIU
+ scenes-app-mcp-analytics-setup-mode--first-call-with-failure--medium--light:
+ hash: v1.k794b7964.41fc6d58f909da74b3c4f20a969b6bb3db5cf685937c5ea4e6f6f0281b533ca4.fSVTVZD67kOdMdwQ9e2SnBnWZgTkM8R2QqS7ebm3SOY
+ scenes-app-mcp-analytics-setup-mode--first-call-with-failure--narrow--dark:
+ hash: v1.k794b7964.7d49a3eab9d12bb93f2c90739cdb94891530d1effbc823827e289b1db61abd96.ebKwSwI4kFJQo9rru6mVaZYJ3dLKCynawIFn62VrB38
+ scenes-app-mcp-analytics-setup-mode--first-call-with-failure--narrow--light:
+ hash: v1.k794b7964.9f3080ddcb336ea34a110481fd59c9d8bf95bad39045b3b249f05b4580bd226c.A3cp_CQYnVgC8QiRKoVn-4Ip7EtgDGaSIp-nwlqMDhs
+ scenes-app-mcp-analytics-setup-mode--first-call-without-intent--dark:
+ hash: v1.k794b7964.7873046c74c440ba364fc405985290272c3e0f64e58fbc8c55173199ce6d84a8.WlfW_mmXr-E0-G8nRpI3RWRsv6NdOKhGYp7YytCVUNY
+ scenes-app-mcp-analytics-setup-mode--first-call-without-intent--light:
+ hash: v1.k794b7964.0979ae024fe51b58f2eb77b187c47d93a113735634b2a182f3e09a98e2276994.e-WRrxk6MYn3GQBUHopV0VdwAB-0WYhcO_KmdMvUlmA
+ scenes-app-mcp-analytics-setup-mode--make-it-useful--dark:
+ hash: v1.k794b7964.2601f61f5d39bea6922852363fb5cbebd2e9ff690e842f582ea484855a8f1a4a.V7GueEMMTr4-8mo3EXB3_S5wck8m8-A5_k0A9ClxfZc
+ scenes-app-mcp-analytics-setup-mode--make-it-useful--light:
+ hash: v1.k794b7964.a9dfed267fefaeed12511c97be54696cdd1aabb27ba73aadb8131e7774d67fe7.jPM2Z2HiRkbHHcfLVGSBJm6ifASCPy-IG5Og5NLt5b8
+ scenes-app-mcp-analytics-setup-mode--setup-screen--medium--dark:
+ hash: v1.k794b7964.69da4d4be5e309573ae312e1b322073a6491d4b252cd8e134cef61e16bd38794.eGPle455bmDnnIpiSr_wJ9iCFCYxr_0kfhUYClK11a8
+ scenes-app-mcp-analytics-setup-mode--setup-screen--medium--light:
+ hash: v1.k794b7964.d8e9b1344cb55cb6ce95dca011732d524d6f97d248815aa21cd24e51852f28a3.sJonSa_sAQ5G-zzVFcrJ-xOJlPsBy0ditH4r24YrtHo
+ scenes-app-mcp-analytics-setup-mode--setup-screen--narrow--dark:
+ hash: v1.k794b7964.873184b18d7e35e68386fa3bd0bbfc43fd80f2bf03d658f4486007043bffb532.Ssn3fp4V8Kp7F-DPVZ6ZG5nB99W-uvqDth_NfneLAW0
+ scenes-app-mcp-analytics-setup-mode--setup-screen--narrow--light:
+ hash: v1.k794b7964.3f4b33dba9d4f261d1526a62493240262f62aa079545ea94cafd7ffa0567737e.dgjIkq5kDgvwnFOhPcpv3Qk2X_2KN7MZCIRkWqHJYS4
+ 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
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/frontend/src/lib/components/ProductEmptyState/ProductEmptyState.tsx b/frontend/src/lib/components/ProductEmptyState/ProductEmptyState.tsx
index 852e823777ca..87df48554784 100644
--- a/frontend/src/lib/components/ProductEmptyState/ProductEmptyState.tsx
+++ b/frontend/src/lib/components/ProductEmptyState/ProductEmptyState.tsx
@@ -264,11 +264,18 @@ export function ProductEmptyState({ config: baseConfig, mode, preview = false }:
<p className="text-secondary text-sm m-0">{text.lead}</p>
</div>
- {text.hint && callToAction ? (
- <div className="text-xs text-tertiary mt-2">{text.hint}</div>
- ) : null}
-
- {callToAction}
+ {config.SetupCard ? (
+ <config.SetupCard mode={mode} preview={preview}>
+ {callToAction}
+ </config.SetupCard>
+ ) : (
+ <>
+ {text.hint && callToAction ? (
+ <div className="text-xs text-tertiary mt-2">{text.hint}</div>
+ ) : null}
+ {callToAction}
+ </>
+ )}
{config.SetupActions ? <config.SetupActions mode={mode} preview={preview} /> : null}
@@ -298,14 +305,16 @@ export function ProductEmptyState({ config: baseConfig, mode, preview = false }:
'linear-gradient(135deg, color-mix(in oklab, var(--empty-state-accent) 16%, transparent) 0%, color-mix(in oklab, var(--empty-state-accent) 5%, transparent) 45%, transparent 80%)',
}}
>
- <div className="flex items-center gap-2 text-xs font-semibold text-secondary">
- <span
- className="size-2 rounded-full bg-[var(--empty-state-accent)] dark:bg-[var(--empty-state-accent-dark)] animate-pulse motion-reduce:animate-none"
- aria-hidden="true"
- />
- {config.previewLabel}
- </div>
- <Preview mode={mode} />
+ {config.previewLabel ? (
+ <div className="flex items-center gap-2 text-xs font-semibold text-secondary">
+ <span
+ className="size-2 rounded-full bg-[var(--empty-state-accent)] dark:bg-[var(--empty-state-accent-dark)] animate-pulse motion-reduce:animate-none"
+ aria-hidden="true"
+ />
+ {config.previewLabel}
+ </div>
+ ) : null}
+ <Preview mode={mode} preview={preview} />
</div>
</div>
</div>
diff --git a/frontend/src/lib/components/ProductEmptyState/types.ts b/frontend/src/lib/components/ProductEmptyState/types.ts
index cad172d63ea5..0ca70061e897 100644
--- a/frontend/src/lib/components/ProductEmptyState/types.ts
+++ b/frontend/src/lib/components/ProductEmptyState/types.ts
@@ -145,14 +145,20 @@ export interface ProductEmptyStateConfig {
/** Product-specific installation options below the primary setup action. */
SetupActions?: ComponentType<{ mode: ProductEmptyStateMode; preview: boolean }>
FooterActions?: ComponentType<{ children: ReactNode }>
+ /**
+ * A card that frames the call to action (the terminal card or primary action), passed as
+ * `children`, together with the product's other install routes. The card labels its own
+ * content, so the hint does not render when it is set.
+ */
+ SetupCard?: ComponentType<{ mode: ProductEmptyStateMode; preview: boolean; children: ReactNode }>
docsUrl?: string
/** Target of the small "Or configure manually" link; falls back to `docsUrl` */
manualSetupUrl?: string
- /** Rendered as "<previewLabel>" with a pulsing live dot, above the preview */
- previewLabel: string
+ /** Rendered as "<previewLabel>" with a pulsing live dot, above the preview. Omit for a preview that labels itself. */
+ previewLabel?: string
previewClassName?: string
/** Self-animating signature preview populated with realistic fake data */
- Preview: ComponentType<{ mode: ProductEmptyStateMode }>
+ Preview: ComponentType<{ mode: ProductEmptyStateMode; preview: boolean }>
/** Product-specific live status line (e.g. a "listening for events" indicator), rendered under the command block */
statusIndicator?: ReactNode
/**
diff --git a/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx b/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
index 4e110faa9947..3f288ae7f634 100644
--- a/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
+++ b/products/mcp_analytics/frontend/MCPAnalyticsScene.tsx
@@ -28,6 +28,7 @@ import { MCPAnalyticsMissingCapabilities } from './missingCapabilities/MCPAnalyt
import { MCPAnalyticsNotifications } from './notifications/MCPAnalyticsNotifications'
import { mcpAnalyticsNotificationsLogic } from './notifications/mcpAnalyticsNotificationsLogic'
import { MCPSessionsPlaylist } from './sessions/MCPSessionsPlaylist'
+import { MCPSetupMode } from './setupMode/MCPSetupMode'
export const scene: SceneExport = {
component: MCPAnalyticsScene,
@@ -126,6 +127,7 @@ export function MCPAnalyticsScene(): JSX.Element {
return (
<SceneContent>
+ <MCPSetupMode />
<MCPAnalyticsSceneMenuBar />
<SceneTitleSection
name="MCP analytics"
diff --git a/products/mcp_analytics/frontend/emptyState/MCPSetupCard.tsx b/products/mcp_analytics/frontend/emptyState/MCPSetupCard.tsx
new file mode 100644
index 000000000000..af0fdfada7ee
--- /dev/null
+++ b/products/mcp_analytics/frontend/emptyState/MCPSetupCard.tsx
@@ -0,0 +1,78 @@
+import { useActions, useValues } from 'kea'
+import type { ReactNode } from 'react'
+
+import { IconCopy } from '@posthog/icons'
+import { LemonButton } from '@posthog/lemon-ui'
+
+import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'
+import type { ProductEmptyStateMode } from 'lib/components/ProductEmptyState/types'
+import { copyToClipboard } from 'lib/utils/copyToClipboard'
+
+import { ProductKey } from '~/queries/schema/schema-general'
+
+import { MCPListeningIndicator } from '../onboarding/MCPAnalyticsInstall'
+import { MCPSetupMode } from '../setupMode/MCPSetupMode'
+import { mcpAnalyticsSetupLogic } from './mcpAnalyticsSetupLogic'
+
+const COPY = {
+ title: 'Step 1: Wrap your MCP server',
+ wizard: 'Run the Wizard',
+ agent: 'Or ask your agent',
+}
+
+/**
+ * The setup screen's install card while setup mode is on: the wizard command the shared empty state
+ * renders as `children`, the agent prompt as the second route, and the listening status. Copying either
+ * one opens setup mode.
+ */
+export function MCPSetupCard({
+ mode,
+ preview,
+ children,
+}: {
+ mode: ProductEmptyStateMode
+ preview: boolean
+ children: ReactNode
+}): JSX.Element {
+ const { agentPrompt } = useValues(mcpAnalyticsSetupLogic)
+ const { reportSetupInteraction } = useActions(productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }))
+
+ return (
+ <div className="mt-2 flex flex-col overflow-hidden rounded border border-primary bg-surface-primary">
+ <span className="px-4 pb-1 pt-3.5 text-base font-semibold">{COPY.title}</span>
+ {children ? (
+ <div className="flex flex-col gap-2 px-4 py-2.5">
+ <span className="text-xs font-semibold text-secondary">{COPY.wizard}</span>
+ {children}
+ </div>
+ ) : null}
+ {agentPrompt ? (
+ <div className="flex flex-col gap-2 px-4 pb-4 pt-2.5">
+ <span className="text-xs font-semibold text-secondary">{COPY.agent}</span>
+ <div className="flex min-w-0 items-center gap-2 rounded border border-primary bg-surface-primary py-1 pl-3 pr-1">
+ <span className="min-w-0 flex-1 truncate font-mono text-xs text-secondary">{agentPrompt}</span>
+ <LemonButton
+ size="small"
+ type="secondary"
+ icon={<IconCopy />}
+ onClick={() =>
+ void copyToClipboard(agentPrompt, 'installation prompt').then((copied) => {
+ if (copied) {
+ reportSetupInteraction('agent prompt copied', mode, 'agent', preview)
+ }
+ })
+ }
+ data-attr="mcp-analytics-copy-agent-prompt"
+ >
+ Copy prompt
+ </LemonButton>
+ </div>
+ </div>
+ ) : null}
+ <div className="border-t border-primary px-4 py-2.5 text-xs">
+ <MCPListeningIndicator />
+ </div>
+ <MCPSetupMode />
+ </div>
+ )
+}
diff --git a/products/mcp_analytics/frontend/emptyState/MCPSetupDemoCard.tsx b/products/mcp_analytics/frontend/emptyState/MCPSetupDemoCard.tsx
new file mode 100644
index 000000000000..ab51138f19f8
--- /dev/null
+++ b/products/mcp_analytics/frontend/emptyState/MCPSetupDemoCard.tsx
@@ -0,0 +1,34 @@
+import { useActions } from 'kea'
+
+import * as basketballCoachPng from '@posthog/brand/hoggies/png/basketball-coach'
+
+import { pngHoggie } from 'lib/brand/hoggies'
+import { productSetupStatusLogic } from 'lib/components/ProductEmptyState/productSetupStatusLogic'
+import type { ProductEmptyStateMode } from 'lib/components/ProductEmptyState/types'
+
+import { ProductKey } from '~/queries/schema/schema-general'
+
+import { HedgehogTipCard } from '../components/HedgehogTipCard'
+
+const HedgehogCoach = pngHoggie(basketballCoachPng)
+
+// The public leaderboard is built from PostHog's own MCP server, the same data this product shows.
+const DEMO_URL = 'https://posthog.com/mcp/leaderboard?utm_medium=in-product&utm_campaign=mcp-analytics-empty-state'
+
+/** For visitors who want to see the product before they have a server to instrument. */
+export function MCPSetupDemoCard({ mode, preview }: { mode: ProductEmptyStateMode; preview: boolean }): JSX.Element {
+ const { reportSetupInteraction } = useActions(productSetupStatusLogic({ productKey: ProductKey.MCP_ANALYTICS }))
+ return (
+ <HedgehogTipCard
+ Hedgehog={HedgehogCoach}
+ title="Not running an MCP server yet?"
+ body="See how agents use PostHog's own MCP server in our demo (yes, we had to rank the robots in a leaderboard)."
+ link={{
+ label: 'MCP Leaderboard',
+ to: DEMO_URL,
+ dataAttr: 'mcp-analytics-setup-demo',
+ onClick: () => reportSetupInteraction('demo clicked', mode, null, preview),
+ }}
+ />
+ )
+}
diff --git a/products/mcp_analytics/frontend/emptyState/MCPSetupSidebar.tsx b/products/mcp_analytics/frontend/emptyState/MCPSetupSidebar.tsx
new file mode 100644
index 000000000000..6abeec856188
--- /dev/null
+++ b/products/mcp_analytics/frontend/emptyState/MCPSetupSidebar.tsx
@@ -0,0 +1,13 @@
+import type { ProductEmptyStateMode } from 'lib/components/ProductEmptyState/types'
+
+import { MCPHowItWorks } from './MCPHowItWorks'
+import { MCPSetupDemoCard } from './MCPSetupDemoCard'
+
+export function MCPSetupSidebar({ mode, preview }: { mode: ProductEmptyStateMode; preview: boolean }): JSX.Element {
+ return (
+ <div className="flex flex-col gap-4">
+ <MCPHowItWorks mode={mode} preview={preview} />
+ <MCPSetupDemoCard mode={mode} preview={preview} />
+ </div>
+ )
+}
diff --git a/products/mcp_analytics/frontend/emptyState/mcpAnalyticsEmptyState.tsx b/products/mcp_analytics/frontend/emptyState/mcpAnalyticsEmptyState.tsx
index d8e851e4902b..52b0c1d0eebe 100644
--- a/products/mcp_analytics/frontend/emptyState/mcpAnalyticsEmptyState.tsx
+++ b/products/mcp_analytics/frontend/emptyState/mcpAnalyticsEmptyState.tsx
@@ -3,12 +3,15 @@ import { IconMCP } from '@posthog/icons'
import { pngHoggie } from 'lib/brand/hoggies'
import type { SceneProductEmptyState } from 'lib/components/ProductEmptyState/types'
+import { FEATURE_FLAGS } from 'lib/constants'
import { ProductKey } from '~/queries/schema/schema-general'
import { mcpAnalyticsOnboardingLogic } from '../mcpAnalyticsOnboardingLogic'
import { MCP_ANALYTICS_DOCS_URL, MCPListeningIndicator } from '../onboarding/MCPAnalyticsInstall'
import { MCPAnalyticsSetupActions } from './MCPAnalyticsSetupActions'
+import { MCPSetupCard } from './MCPSetupCard'
+import { MCPSetupSidebar } from './MCPSetupSidebar'
import { MCPToolCallPreview } from './MCPToolCallPreview'
const HedgehogPuzzle = pngHoggie(puzzlePng)
@@ -41,5 +44,15 @@ export const mcpAnalyticsEmptyState: SceneProductEmptyState = {
previewLabel: 'Tool calls, once connected',
Preview: MCPToolCallPreview,
statusIndicator: <MCPListeningIndicator />,
+ featureFlagOverrides: {
+ [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]: {
+ SetupActions: undefined,
+ SetupCard: MCPSetupCard,
+ // The setup card renders the indicator itself, as its footer.
+ statusIndicator: undefined,
+ previewLabel: undefined,
+ Preview: MCPSetupSidebar,
+ },
+ },
},
}
diff --git a/products/mcp_analytics/frontend/setupMode/MCPSetupMode.stories.tsx b/products/mcp_analytics/frontend/setupMode/MCPSetupMode.stories.tsx
new file mode 100644
index 000000000000..59737d411dfb
--- /dev/null
+++ b/products/mcp_analytics/frontend/setupMode/MCPSetupMode.stories.tsx
@@ -0,0 +1,141 @@
+import { Meta, StoryObj } from '@storybook/react'
+
+import { ProductEmptyState } from 'lib/components/ProductEmptyState/ProductEmptyState'
+import { productEmptyStateStory } from 'lib/components/ProductEmptyState/storybookHelpers'
+import { FEATURE_FLAGS } from 'lib/constants'
+
+import { mswDecorator } from '~/mocks/browser'
+import preflightJson from '~/mocks/fixtures/_preflight.json'
+import { EMPTY_PAGINATED_RESPONSE } from '~/mocks/handlers'
+
+import { mcpAnalyticsEmptyState } from '../emptyState/mcpAnalyticsEmptyState'
+import type { MCPActivityOverviewApi, MCPActivityRecentCallApi } from '../generated/api.schemas'
+import { MCPSetupModeView, type MCPSetupModeViewProps } from './MCPSetupModeView'
+
+// Invented fixtures: an example docs server called from two clients.
+const SUCCESS_CALL: MCPActivityRecentCallApi = {
+ timestamp: '2026-06-07T11:59:40Z',
+ tool: 'search_docs',
+ intent: 'Find the rate limit for the billing API so I can add retries',
+ is_error: false,
+ error_message: null,
+ duration_ms: 142,
+ client_name: 'Claude Code',
+}
+
+const FAILED_CALL: MCPActivityRecentCallApi = {
+ timestamp: '2026-06-07T11:59:55Z',
+ tool: 'create_issue',
+ intent: 'Open a ticket for the 429 errors the user reported',
+ is_error: true,
+ error_message: 'ValidationError: missing required field "team_id"',
+ duration_ms: 88,
+ client_name: 'Cursor',
+}
+
+const BASE: MCPSetupModeViewProps = {
+ step: 'connect',
+ connectState: { kind: 'waiting' },
+ recentCalls: null,
+ recentCallsFailed: false,
+ onExit: () => {},
+ onAskPostHogAI: () => {},
+ onGoToUseful: () => {},
+}
+
+const OVERVIEW: MCPActivityOverviewApi = {
+ stats: {
+ total_calls: 2,
+ distinct_tools: 2,
+ distinct_sessions: 1,
+ distinct_clients: 2,
+ calls_with_intent: 2,
+ error_calls: 1,
+ missing_capability_reports: 0,
+ },
+ top_tools: [],
+ clients: [],
+ recent_calls: [FAILED_CALL, SUCCESS_CALL],
+}
+
+const meta: Meta<typeof MCPSetupModeView> = {
+ title: 'Scenes-App/MCP Analytics/Setup mode',
+ component: MCPSetupModeView,
+ decorators: [
+ (Story) => (
+ <div className="flex h-screen">
+ <Story />
+ </div>
+ ),
+ ],
+ parameters: {
+ layout: 'fullscreen',
+ viewMode: 'story',
+ mockDate: '2026-06-07T12:00:00Z',
+ },
+ args: BASE,
+}
+export default meta
+
+type Story = StoryObj<typeof MCPSetupModeView>
+
+export const Connect: Story = {
+ parameters: { testOptions: { viewportWidths: ['narrow', 'medium'], waitForLoadersToDisappear: false } },
+}
+
+export const Connected: Story = {
+ args: { connectState: { kind: 'connected' } },
+ parameters: { testOptions: { waitForLoadersToDisappear: false } },
+}
+
+export const FirstCallSuccess: Story = {
+ args: { step: 'first-call', recentCalls: [SUCCESS_CALL] },
+}
+
+export const FirstCallWithFailure: Story = {
+ args: { step: 'first-call', recentCalls: [FAILED_CALL, SUCCESS_CALL] },
+ parameters: { testOptions: { viewportWidths: ['narrow', 'medium'] } },
+}
+
+export const FirstCallWithoutIntent: Story = {
+ args: { step: 'first-call', recentCalls: [{ ...SUCCESS_CALL, intent: null, client_name: null }] },
+}
+
+export const MakeItUseful: Story = {
+ args: { step: 'useful' },
+ decorators: [
+ mswDecorator({
+ get: {
+ '/_preflight': { ...preflightJson, cloud: true, realm: 'cloud' },
+ '/api/projects/:team_id/mcp_analytics/sessions/activity_overview/': OVERVIEW,
+ '/api/projects/:team_id/hog_functions': EMPTY_PAGINATED_RESPONSE,
+ '/api/projects/:team_id/subscriptions': EMPTY_PAGINATED_RESPONSE,
+ },
+ }),
+ ],
+ parameters: {
+ featureFlags: [FEATURE_FLAGS.SUBSCRIPTION_AI_PROMPT],
+ testOptions: { waitForSelector: '[data-attr=mcp-analytics-activity-next-step-weekly-report]' },
+ },
+}
+
+const SETUP_SCREEN = productEmptyStateStory(mcpAnalyticsEmptyState, 'needs-setup', {
+ mocks: {
+ get: { '/_preflight': { ...preflightJson, cloud: true, realm: 'cloud' } },
+ post: {
+ // Onboarding signals: [has_initialize, tool_calls_total, tool_calls_7d, first_call_at]
+ '/api/environments/:team_id/query/:kind': [200, { results: [[0, 0, 0, '1970-01-01T00:00:00Z']] }],
+ },
+ },
+})
+
+// The setup screen with setup mode on: both install routes in one card, and the how-it-works sidebar above the
+// demo card. At medium width the stacked sidebar is wide enough for its three-column layout.
+export const SetupScreen: StoryObj<typeof ProductEmptyState> = {
+ ...SETUP_SCREEN,
+ parameters: {
+ ...SETUP_SCREEN.parameters,
+ featureFlags: [FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE],
+ testOptions: { ...SETUP_SCREEN.parameters?.testOptions, viewportWidths: ['narrow', 'medium', 'wide'] },
+ },
+}
diff --git a/products/mcp_analytics/frontend/setupMode/MCPSetupMode.tsx b/products/mcp_analytics/frontend/setupMode/MCPSetupMode.tsx
new file mode 100644
index 000000000000..1a5cf1a15f6a
--- /dev/null
+++ b/products/mcp_analytics/frontend/setupMode/MCPSetupMode.tsx
@@ -0,0 +1,54 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonModal } from '@posthog/lemon-ui'
+
+import { FEATURE_FLAGS } from 'lib/constants'
+import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
+
+import { mcpSetupModeLogic } from './mcpSetupModeLogic'
+import { MCPSetupModeView } from './MCPSetupModeView'
+import { SetupModeDevControls } from './SetupModeDevControls'
+
+function MCPSetupModeOverlay(): JSX.Element | null {
+ const { isOpen, step, connectState, recentCalls, recentCallsFailed } = useValues(mcpSetupModeLogic)
+ const { exitSetupMode, goToUsefulStep, askPostHogAI } = useActions(mcpSetupModeLogic)
+ if (!isOpen) {
+ return null
+ }
+ return (
+ <LemonModal
+ // The logic handles Escape, so the modal itself never closes.
+ closable={false}
+ fullScreen
+ simple
+ // The gate remounts this host when the first call lands. Showing the modal at full opacity from
+ // its first frame, and unmounting it on exit, keeps the swap and the exit free of a fade over the scene.
+ className="!opacity-100 !transform-none"
+ data-attr="mcp-analytics-setup-mode"
+ >
+ <MCPSetupModeView
+ step={step}
+ connectState={connectState}
+ recentCalls={recentCalls}
+ recentCallsFailed={recentCallsFailed}
+ onExit={exitSetupMode}
+ onAskPostHogAI={askPostHogAI}
+ onGoToUseful={goToUsefulStep}
+ />
+ <SetupModeDevControls />
+ </LemonModal>
+ )
+}
+
+/**
+ * Mounted by both the empty state and the scene, because the gate swaps one for the other when the
+ * first call lands. The state lives in the URL, so the takeover carries across the swap.
+ */
+export function MCPSetupMode(): JSX.Element | null {
+ const { featureFlags } = useValues(featureFlagLogic)
+ // Checked here rather than in the logic so that, with the flag off, nothing extra mounts.
+ if (!featureFlags[FEATURE_FLAGS.MCP_ANALYTICS_SETUP_MODE]) {
+ return null
+ }
+ return <MCPSetupModeOverlay />
+}
diff --git a/products/mcp_analytics/frontend/setupMode/MCPSetupModeView.tsx b/products/mcp_analytics/frontend/setupMode/MCPSetupModeView.tsx
new file mode 100644
index 000000000000..ca402304b2b4
--- /dev/null
+++ b/products/mcp_analytics/frontend/setupMode/MCPSetupModeView.tsx
@@ -0,0 +1,117 @@
+import { IconCheck, IconMCP } from '@posthog/icons'
+import { LemonButton, Spinner } from '@posthog/lemon-ui'
+
+import { cn } from 'lib/utils/css-classes'
+
+import type { MCPActivityRecentCallApi } from '../generated/api.schemas'
+import { SetupConnectStep } from './SetupConnectStep'
+import { SetupFirstCallStep } from './SetupFirstCallStep'
+import { MCP_SETUP_STEPS, type MCPConnectState, type MCPSetupExitReason, type MCPSetupStep } from './setupMode'
+import { SetupUsefulStep } from './SetupUsefulStep'
+
+const COPY = {
+ title: 'Set up MCP analytics',
+ exit: 'Back to overview',
+ steps: { connect: 'Connect', 'first-call': 'First call', useful: 'Make it useful' } satisfies Record<
+ MCPSetupStep,
+ string
+ >,
+}
+
+export interface MCPSetupModeViewProps {
+ /** `null` while the onboarding signals have not answered yet. */
+ step: MCPSetupStep | null
+ connectState: MCPConnectState
+ recentCalls: MCPActivityRecentCallApi[] | null
+ recentCallsFailed: boolean
+ onExit: (reason: MCPSetupExitReason) => void
+ onAskPostHogAI: (prompt: string) => void
+ onGoToUseful: () => void
+}
+
+function StepRail({ current }: { current: MCPSetupStep | null }): JSX.Element {
+ const currentIndex = current ? MCP_SETUP_STEPS.indexOf(current) : -1
+ return (
+ <ol className="m-0 flex list-none flex-wrap items-center gap-x-3 gap-y-1 p-0 text-sm" aria-label="Setup steps">
+ {MCP_SETUP_STEPS.map((step, index) => {
+ const done = index < currentIndex
+ const active = index === currentIndex
+ return (
+ <li
+ key={step}
+ className={cn('flex items-center gap-1.5', active ? 'font-semibold' : 'text-secondary')}
+ aria-current={active ? 'step' : undefined}
+ >
+ <span
+ className={cn(
+ 'flex size-5 shrink-0 items-center justify-center rounded-full border text-xs',
+ done && 'border-success bg-success text-white',
+ active && 'border-primary-3000 bg-primary-3000 text-white',
+ !done && !active && 'border-primary'
+ )}
+ >
+ {done ? <IconCheck /> : index + 1}
+ </span>
+ {COPY.steps[step]}
+ </li>
+ )
+ })}
+ </ol>
+ )
+}
+
+function StepBody({ step, ...props }: MCPSetupModeViewProps & { step: MCPSetupStep }): JSX.Element {
+ if (step === 'connect') {
+ return <SetupConnectStep connectState={props.connectState} />
+ }
+ if (step === 'first-call') {
+ return (
+ <SetupFirstCallStep
+ calls={props.recentCalls}
+ loadFailed={props.recentCallsFailed}
+ onNext={props.onGoToUseful}
+ />
+ )
+ }
+ return <SetupUsefulStep onFinish={() => props.onExit('finished')} onAskPostHogAI={props.onAskPostHogAI} />
+}
+
+/** The fullscreen setup walkthrough: a header with the step rail, and the current step below it. */
+export function MCPSetupModeView(props: MCPSetupModeViewProps): JSX.Element {
+ const { step, onExit } = props
+ return (
+ <div className="@container/setup-mode flex min-h-0 w-full flex-1 flex-col bg-primary">
+ <header className="flex shrink-0 flex-wrap items-center justify-between gap-x-6 gap-y-2 border-b border-primary px-4 py-3">
+ <span className="flex items-center gap-2 font-semibold">
+ <IconMCP className="text-lg" />
+ {COPY.title}
+ </span>
+ <span className="order-last w-full @min-[48rem]/setup-mode:order-none @min-[48rem]/setup-mode:w-auto">
+ <StepRail current={step} />
+ </span>
+ <LemonButton
+ size="small"
+ type="secondary"
+ onClick={() => onExit('back')}
+ data-attr="mcp-analytics-setup-mode-exit"
+ >
+ {COPY.exit}
+ </LemonButton>
+ </header>
+ <div className="min-h-0 flex-1 overflow-y-auto">
+ {/* The auto margins center a short step in the window and let a tall one scroll from the top. */}
+ <div className="flex min-h-full flex-col px-4 py-8 @min-[56rem]/setup-mode:px-8">
+ <div className="mx-auto my-auto w-full max-w-6xl">
+ {step ? (
+ <StepBody {...props} step={step} />
+ ) : (
+ <div className="flex justify-center">
+ <Spinner className="text-2xl" />
+ </div>
+ )}
+ </div>
+ </div>
+ </div>
+ </div>
+ )
+}
diff --git a/products/mcp_analytics/frontend/setupMode/SetupModeDevControls.tsx b/products/mcp_analytics/frontend/setupMode/SetupModeDevControls.tsx
new file mode 100644
index 000000000000..7359b3b454d3
--- /dev/null
+++ b/products/mcp_analytics/frontend/setupMode/SetupModeDevControls.tsx
@@ -0,0 +1,102 @@
+import { useValues } from 'kea'
+import { useState } from 'react'
+
+import { LemonButton } from 'lib/lemon-ui/LemonButton'
+import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
+import { teamLogic } from 'scenes/teamLogic'
+
+type DevEventKind = 'connect' | 'call' | 'fail'
+
+const DEV_EVENTS: Record<DevEventKind, { label: string; event: string; properties: Record<string, unknown> }> = {
+ connect: {
+ label: 'Connect server',
+ event: '$mcp_initialize',
+ properties: { $mcp_client_name: 'claude-code', $mcp_server_name: 'dev-server' },
+ },
+ call: {
+ label: 'Send tool call',
+ event: '$mcp_tool_call',
+ properties: {
+ $mcp_client_name: 'claude-code',
+ $mcp_server_name: 'dev-server',
+ $mcp_tool_name: 'search_docs',
+ $mcp_intent: 'Find the rate limit for the billing API so I can add retries',
+ $mcp_is_error: false,
+ $mcp_duration_ms: 142,
+ $mcp_response: 'Billing API: 100 requests per minute per key.',
+ },
+ },
+ fail: {
+ label: 'Send failed call',
+ event: '$mcp_tool_call',
+ properties: {
+ $mcp_client_name: 'cursor',
+ $mcp_server_name: 'dev-server',
+ $mcp_tool_name: 'create_issue',
+ $mcp_intent: 'Open a ticket for the 429 errors the user reported',
+ $mcp_is_error: true,
+ $mcp_duration_ms: 88,
+ $mcp_error_message: 'ValidationError: missing required field "team_id"',
+ },
+ },
+}
+
+/**
+ * Dev-only buttons that send real MCP events to the current project, so setup mode advances through
+ * the same ingestion and polling a live server would trigger. Renders nothing in production builds.
+ */
+export function SetupModeDevControls(): JSX.Element | null {
+ if (process.env.NODE_ENV !== 'development') {
+ return null
+ }
+ return <SetupModeDevControlsContent />
+}
+
+function SetupModeDevControlsContent(): JSX.Element | null {
+ const { currentTeam } = useValues(teamLogic)
+ const [sending, setSending] = useState<DevEventKind | null>(null)
+
+ if (!currentTeam?.api_token) {
+ return null
+ }
+ const token = currentTeam.api_token
+
+ const send = async (kind: DevEventKind): Promise<void> => {
+ const { event, properties } = DEV_EVENTS[kind]
+ setSending(kind)
+ try {
+ const response = await fetch('/e/', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ api_key: token, event, distinct_id: 'setup-mode-dev', properties }),
+ })
+ if (!response.ok) {
+ throw new Error(`capture answered ${response.status}`)
+ }
+ lemonToast.success(`Sent ${event}. Setup mode moves on at its next poll.`)
+ } catch (error) {
+ lemonToast.error(`Couldn't send ${event}: ${String(error)}`)
+ } finally {
+ setSending(null)
+ }
+ }
+
+ return (
+ // Bottom center, clear of toasts (bottom right) and the wizard sync debug panel (bottom left).
+ <div className="fixed bottom-2 left-1/2 z-[9999] -translate-x-1/2 flex items-center gap-1 rounded border bg-surface-primary p-1 text-xs shadow-md">
+ <span className="px-1 font-semibold">Dev: advance setup</span>
+ {(Object.keys(DEV_EVENTS) as DevEventKind[]).map((kind) => (
+ <LemonButton
+ key={kind}
+ size="xsmall"
+ type="secondary"
+ loading={sending === kind}
+ disabledReason={sending && sending !== kind ? 'Sending another event' : undefined}
+ onClick={() => void send(kind)}
+ >
+ {DEV_EVENTS[kind].label}
+ </LemonButton>
+ ))}
+ </div>
+ )
+}