Implementing MCP UI apps

MCP UI apps are interactive React visualizations that render alongside tool results in MCP clients (e.g. Claude Desktop). They're built with the Mosaic component library and served via Cloudflare Workers Static Assets.

Full reference: services/mcp/CONTRIBUTING.md.

Quick workflow

# 1. Create view components in your product's mcp/apps/ directory
#    (see "View components" below)

# 2. Add ui_apps entries to your product's mcp/tools.yaml
#    (see "YAML configuration" below)

# 3. Link tools to apps with ui_app: <key> in the tools section

# 4. Generate entry points + registry, then build
pnpm --filter=@posthog/mcp run generate:ui-apps
pnpm --filter=@posthog/mcp run build

When to add a UI app

When an MCP tool returns structured data that benefits from visual presentation — tables, detail views, charts, status badges, etc. Without a UI app, tool results are shown as plain text/JSON in the chat.

Architecture

products/{product}/mcp/
  apps/                          # React view components (you write these)
    EntityView.tsx               # Detail view
    EntityListView.tsx           # List view (uses ListDetailView from Mosaic)
    index.ts                     # Barrel exports
  tools.yaml                     # YAML config: ui_apps + tools

services/mcp/
  src/ui-apps/apps/
    generated/                   # Auto-generated entry points (don't edit)
    debug.tsx                    # Custom/manual entry points
    query-results.tsx
  src/resources/
    ui-apps.generated.ts         # Auto-generated: URI constants, UiAppKey, URI_MAP, UI_APPS
    ui-apps.ts                   # Hand-authored: withUiApp(), registerUiAppResources()
  scripts/
    generate-ui-apps.ts          # The generator — reads YAML, writes entry points + registry
    yaml-config-schema.ts        # Zod schemas for YAML validation (source of truth for field definitions)

View components

Place view components in products/{product}/mcp/apps/.

Detail view — renders a single entity:

import { type ReactElement } from 'react'
import { DescriptionList } from '@posthog/mcp-ui'
import { Card, CardHeader, CardTitle, CardContent } from '@posthog/quill'

export interface MyEntityData {
  id: number
  name: string
  // ... fields from the API response
}

export function MyEntityView({ data }: { data: MyEntityData }): ReactElement {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{data.title}</CardTitle>
      </CardHeader>
      <CardContent>
        <DescriptionList items={[{ label: 'ID', value: String(data.id) }]} />
      </CardContent>
    </Card>
  )
}

List view — uses ListDetailView from Mosaic for the list-to-detail state machine:

import { type ReactElement, type ReactNode } from 'react'
import { DataTable, type DataTableColumn, ListDetailView } from '@posthog/mcp-ui'
import { MyEntityView, type MyEntityData } from './MyEntityView'

export interface MyEntityListData {
  results: MyEntityData[]
  _posthogUrl?: string
}

export interface MyEntityListViewProps {
  data: MyEntityListData
  onMyEntityClick?: (entity: MyEntityData) => Promise<MyEntityData | null>
}

export function MyEntityListView({ data, onMyEntityClick }: MyEntityListViewProps): ReactElement {
  return (
    <ListDetailView<MyEntityData>
      onItemClick={onMyEntityClick}
      backLabel="All entities"
      getItemName={(e) => e.name}
      renderDetail={(e) => <MyEntityView data={e} />}
      renderList={(handleClick) => {
        const columns: DataTableColumn<MyEntityData>[] = [
          {
            key: 'name',
            header: 'Name',
            sortable: true,
            render: (row): ReactNode =>
              onMyEntityClick ? (
                <button onClick={() => handleClick(row)} className="text-link underline ...">
                  {row.name}
                </button>
              ) : (
                row.name
              ),
          },
        ]

        return (
          <div className="p-4">
            <div className="flex flex-col gap-2">
              <div className="flex items-center justify-between">
                <span className="text-sm text-muted-foreground">
                  {data.results.length} entit{data.results.length === 1 ? 'y' : 'ies'}
                </span>
              </div>
              <DataTable<CohortData>
                columns={columns}
                data={data.results}
                pageSize={10}
                defaultSort={{ key: 'name', direction: 'asc' }}
                emptyMessage="No entities found"
              />
            </div>
          </div>
        )
      }}
    />
  )
}

Barrel export (index.ts):

export { MyEntityView, type MyEntityData } from './MyEntityView'
export { MyEntityListView, type MyEntityListData, type MyEntityListViewProps } from './MyEntityListView'

YAML configuration

The ui_apps section in products/{product}/mcp/tools.yaml defines UI apps. Each key becomes the app identifier (used in URIs, constants, and withUiApp calls).

There are three app types: detail, list, and custom.

type: detail — single-entity view

Renders one entity using a view component wrapped in AppWrapper.

Required fields:

Optional fields (derived by convention when omitted):

Minimal example:

ui_apps:
  action:
    type: detail
    view_prop: action

Example with overrides (when conventions don't match the actual code):

ui_apps:
  llm-costs:
    type: detail
    view_prop: data
    data_type: LLMCostsData # convention would produce LlmCostsData
    view_component: LLMCostsView # convention would produce LlmCostsView

type: list — list with drill-down

Renders a list component. When an item is clicked, calls a detail tool via app.callServerTool() and shows the detail view inline. Falls back to a chat message if the MCP client doesn't support tool calls from apps.

Required fields:

Optional fields with behavioral defaults:

Optional fields with convention defaults (same pattern as detail apps):

Minimal example:

ui_apps:
  action-list:
    type: list
    detail_tool: action-get

Example with overrides:

ui_apps:
  feature-flag-list:
    type: list
    detail_tool: feature-flag-get-definition
    detail_args: '{ flagId: item.id }' # tool expects flagId, not id
    item_name_field: key # flags are identified by key, not name
    click_prop: onFlagClick # component uses onFlagClick, not onFeatureFlagClick

type: custom — handwritten entry point

For apps that need fully custom logic (e.g. debug.tsx, query-results.tsx). The generator does NOT create an entry point — you maintain it manually at services/mcp/src/ui-apps/apps/{key}.tsx. Only the registry entry is generated.

Required fields:

Example:

ui_apps:
  query-results:
    type: custom
    app_name: Query Results
    description: Interactive visualization for PostHog query results

Where the schemas live

The Zod schemas that validate these YAML fields live in services/mcp/scripts/yaml-config-schema.ts. Each field has a JSDoc comment explaining its purpose and default.

To add a new field to an app type:

1. Add it to the relevant Zod schema (DetailUiAppSchema, ListUiAppSchema, or CustomUiAppSchema) with .optional() if it has a default
2. Add it to the matching Resolved* interface (ResolvedDetailUiApp or ResolvedListUiApp)
3. Add the default derivation in resolveDetailApp() or resolveListApp() in generate-ui-apps.ts
4. Use the resolved value in generateDetailApp() or generateListApp()

All schemas use .strict() — unknown keys are rejected at build time, catching typos.

Linking tools to UI apps

In the tools section of the same YAML file, use ui_app to reference a ui_apps key:

tools:
  my-entity-get:
    operation: my_entities_retrieve
    enabled: true
    ui_app: my-entity # references ui_apps.my-entity
  my-entity-list:
    operation: my_entities_list
    enabled: true
    ui_app: my-entity-list # references ui_apps.my-entity-list

The generator validates that every ui_app value points to a key that exists in some ui_apps section across all YAML files.

For handwritten tools (not YAML-generated), use withUiApp in TypeScript:

import { withUiApp } from '@/resources/ui-apps'
import { withPostHogUrl, type WithPostHogUrl } from '@/tools/tool-utils'
import type { Context, ToolBase } from '@/tools/types'

type Result = WithPostHogUrl<MyEntityData>

export default (): ToolBase<typeof schema, Result> =>
  withUiApp('my-entity', {
    name: 'my-entity-get',
    schema,
    handler: async (context, params) => {
      const projectId = await context.stateManager.getProjectId()
      const data = await fetchEntity(context, params)
      return await withPostHogUrl(context, data, `/my-entities/${data.id}`)
    },
  })

The appKey parameter is type-checked against the generated UiAppKey union — invalid keys are compile-time errors.

CI validation

CI checks that generated files are up to date in both ci-mcp.yml and ci-mcp-ui-apps.yml. If you change YAML ui_apps sections, run pnpm --filter=@posthog/mcp run generate:ui-apps and commit the result.