: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
/**
* MCP client profiling and capability detection.
*
* `clientInfo.name` is what a client self-reports during the `initialize`
* handshake. We use substring matching (with separators stripped and case
* normalized) so variants like "claude-code", "Claude Code", "claude-code-cli",
* and "claude-code/1.2.3" all resolve to the same form.
*
* The `MCPClientProfile` class owns all per-client behavior decisions:
*
* - `isToolsModeClient()` matches the clients that keep the full per-tool
* roster ("tools" mode) instead of the single-exec CLI default. This is the
* only way a client lands in tools mode without an explicit `?mode=` /
* `x-posthog-mcp-mode` override — see `resolveMode`.
*
* - `isCliModeEnabled()` matches clients that should drop `structuredContent`
* when a `formatted_results` override is set. Every known Anthropic client
* qualifies — matched against the `x-anthropic-client` (`vendorClient`)
* header, since Anthropic pools MCP transports across all its products and
* reports the live one there. Other coding agents are matched by
* self-reported client name. Cursor is deliberately excluded from the name
* match — it reads text for the model and renders `structuredContent` in UI,
* so it does not need the formatted-results workaround.
*
* - `isPostHogCodeConsumer()` matches the `x-posthog-mcp-consumer` header
* sent by the PostHog Desktop Tasks wrapper.
*
* - `isRenderUiHost()` uses declared MCP Apps support when the client sends it.
* Otherwise it matches Claude web/desktop, Cowork, and the exact `openai-mcp`
* client name.
*
* - `isClaudeChatHost()` matches Claude web/desktop only — the chat surfaces that
* report `supportsInstructions` but never surface the `instructions` payload to
* the model. Used to keep the env-context on the exec command description for
* them. Cowork surfaces instructions normally, so it is deliberately excluded.
*
* - `capabilities` is a feature-flag-style object describing protocol
* features the client actually implements (e.g. `supportsInstructions` —
* Codex ignores the `instructions` field returned from `initialize`).
*/
function normalizeClientName(s: string): string {
return s.toLowerCase().replace(/[-_\s]+/g, '')
}
function matchesAnyFragment(clientName: string | undefined, fragments: readonly string[]): boolean {
if (!clientName) {
return false
}
const normalized = normalizeClientName(clientName)
if (!normalized) {
return false
}
return fragments.some((fragment) => normalized.includes(normalizeClientName(fragment)))
}
function matchesProductName(value: string | undefined, names: readonly string[]): boolean {
const product = value?.trim().split(/[\s/]/, 1)[0]?.toLowerCase()
return !!product && names.includes(product)
}
// Coding agents and LLM-driven clients that render text rather than MCP Apps UI.
// Matched by `isCliModeEnabled()`, which gates dropping `structuredContent` when a
// `formatted_results` override is set. Mode selection does NOT read this list — CLI
// (single-exec) is the default for every client; `TOOLS_MODE_CLIENT_NAME_FRAGMENTS`
// is the tools-mode allow-list.
export const CODING_AGENT_CLIENT_NAME_FRAGMENTS = [
'claude-code',
'cline',
'roo-code',
'roo-cline',
'continue',
'codex',
'windsurf',
'zed',
'aider',
'copilot',
'gemini-cli',
// Devin self-reports `clientInfo.name` as `Devin`; it's a coding agent and
// benefits from the same single-exec mode.
'devin',
// LibreChat is a general MCP client, but benefits from the same CLI-shaped
// single-exec mode as coding agents.
'librechat',
// Notion AI ships its own `notion-mcp-client` (not a coding agent per se,
// but an LLM-driven consumer that benefits from the same single-exec mode
// and formatted-text rendering as coding agents).
'notion',
// OpenCode is a terminal coding agent (and the engine behind clients like
// OpenWork). It connects through OpenCode's MCP client, which self-reports
// `clientInfo.name` as `opencode`. It renders text, not MCP Apps UI, so it
// wants single-exec mode like the other coding agents.
'opencode',
// Amp is Sourcegraph's coding agent; its MCP client self-reports
// `clientInfo.name` as `amp-mcp-client` and benefits from single-exec mode.
'amp-mcp-client',
// Poke is an LLM-driven assistant that renders text, not MCP Apps UI, so it
// wants the same single-exec mode as the coding agents.
'poke',
// Grok (xAI) — both Grok Build (the terminal coding agent) and the grok.com
// assistant connect custom MCP servers and render text rather than MCP Apps
// UI, so they benefit from the same single-exec mode and formatted-text
// rendering as the other coding agents.
'grok',
// Ando is an LLM-driven assistant (Slack, chat, calls) whose MCP client
// self-reports `clientInfo.name` as `ando-mcp-gateway`; it renders text and
// benefits from the same single-exec mode as the coding agents.
'ando-mcp-gateway',
] as const
// Clients that wedge after a stateless `server/discover` but complete the legacy
// handshake, so discover answers method-not-found to push them back to `initialize`.
// Remove an entry once the client completes the stateless dialect.
export const LEGACY_DIALECT_ONLY_CLIENT_NAME_FRAGMENTS = ['antigravity'] as const
// Clients that keep the full per-tool roster ("tools" mode) instead of the
// single-exec CLI default.
// - Cursor self-reports `clientInfo.name` (`cursor-vscode`, `Cursor`); it sends
// `content[].text` to the model and renders `structuredContent` in its UI, so
// the full roster serves it better than the exec wrapper. Some older Cursor
// builds omit `clientInfo.name` and are only identifiable by their
// `Cursor/x.y.z (...)` User-Agent, hence the UA fragment too.
// - Every OpenAI surface (ChatGPT, Codex, Agent Builder, Responses API) stays
// on the CLI default. OpenAI's shared `openai-mcp` client caches the roster it
// captures for a published plugin and serves that snapshot to every user, so
// the plugin listing pins its mode explicitly with `?mode=` instead of relying
// on a User-Agent label that only some of its requests carry.
export const TOOLS_MODE_CLIENT_NAME_FRAGMENTS = ['cursor'] as const
export const TOOLS_MODE_USER_AGENT_FRAGMENTS = ['cursor'] as const
// Known `x-anthropic-client` (`vendorClient`) header values. Anthropic pools
// MCP transports across all its products and reports the live one in this
// header, so it's the reliable identifier for an Anthropic client (the
// `initialize` body's `clientName` is the pool owner, e.g. `Anthropic/ClaudeAI`).
// Every Anthropic product runs in CLI (single-exec) mode. Matched as normalized
// substrings, so vendor-prefixed shapes like `Anthropic/ClaudeAI` resolve to
// `claudeai`.
export const ANTHROPIC_CLIENT_NAME_FRAGMENTS = ['claudecode', 'claudeai', 'cowork', 'claudedesign'] as const
// Anthropic clients connect through a pooled MCP transport and usually omit the
// `initialize` body's `clientInfo.name`, reporting their live product only in the
// `x-anthropic-client` (`vendorClient`) header. Map that vendor value to the
// canonical client-name token the MCP analytics dashboard buckets on, so these
// sessions are attributed to a real client instead of falling into "Other".
// Mirrors the vendor→name mapping in the dashboard (harnessRegistry.ts and
// models-mcp.md) — keep the three in sync.
const VENDOR_CLIENT_TO_CLIENT_NAME: Readonly<Record<string, string>> = {
claudecode: 'claude-code',
claudeai: 'claude-ai',
cowork: 'cowork',
claudedesign: 'claude-design',
}
/**
* Resolve the client name used for analytics (`$mcp_client_name`) and the API
* client header. Prefers the self-reported `clientInfo.name`; when that's absent
* — as it is for Anthropic clients on the pooled transport — it falls back to a
* canonical name derived from the `x-anthropic-client` vendor header, keeping the
* raw vendor value for any unrecognized Anthropic product. Returns undefined when
* neither is available.
*/
export function resolveEffectiveClientName(
clientName: string | undefined,
vendorClient: string | undefined
): string | undefined {
if (clientName) {
return clientName
}
if (!vendorClient) {
return undefined
}
return VENDOR_CLIENT_TO_CLIENT_NAME[normalizeClientName(vendorClient)] ?? vendorClient
}
// Value sent in `x-posthog-mcp-consumer` by PostHog Desktop (the Tasks sandbox
// wrapper around the Claude Agent SDK) when the task was launched from the
// PostHog Desktop UI. Slack-launched runs send `"slack"` and posthog_ai (Max) runs
// send `"posthog_ai"`; only PostHog Desktop renders MCP UI apps, so this is the
// sole consumer that gates UI-apps payload emission in single-exec mode.
export const POSTHOG_CODE_CONSUMER = 'posthog-code'
// Claude web/desktop and Cowork are MCP Apps hosts that render interactive UI
// (iframes), so the `render-ui` tool is meaningful for them. They send
// `x-anthropic-client: ClaudeAI` / `Cowork` (vs `ClaudeCode` for Claude Code) and
// `User-Agent: Claude-User`. The vendor client is authoritative when present:
// Claude Code is excluded even though it may share the `Claude-User` user-agent.
// The user-agent is a fallback solely for requests that omit the vendor header.
// We deliberately do NOT match `clientName` here — Anthropic pools transports, so
// Claude Code's `clientInfo.name` is also `Anthropic/ClaudeAI`, and matching it
// would misclassify Claude Code as a UI host.
export const ANTHROPIC_UI_HOST_VENDOR_FRAGMENTS = ['claudeai', 'cowork'] as const
// Claude web/desktop never show `instructions` to the model. Cowork does, so it
// is not a chat host even though it is a UI host.
export const ANTHROPIC_CHAT_HOST_VENDOR_FRAGMENTS = ['claudeai'] as const
// Anthropic surfaces that render MCP UI apps on the `exec` response itself, so they
// get the same treatment as the PostHog Desktop consumer. `Cowork` is not one: Claude
// desktop chat reports `Cowork` and mounts an iframe only for a tool that declares
// `_meta.ui.resourceUri` on `tools/list`, which `exec` does not. It renders through
// `render-ui`, like `ClaudeAI`.
export const INLINE_EXEC_UI_APP_VENDOR_FRAGMENTS = ['claudecode'] as const
// User-Agent Anthropic clients send when they connect without the
// `x-anthropic-client` header (Claude.ai web/desktop and internal Anthropic
// tooling). It's a generic Anthropic signal — Claude Code and Cowork can send it
// too — so it drives CLI-mode detection; the UI-host check reuses it as its own
// user-agent fallback.
export const ANTHROPIC_USER_AGENT_FRAGMENTS = ['claude-user'] as const
export const ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS = ANTHROPIC_USER_AGENT_FRAGMENTS
// OpenAI clients send no vendor header, so the shared `openai-mcp` client is matched
// on `clientInfo.name` or the User-Agent product token. The match is exact because a
// substring match on `codex` also matches Codex CLI (`codex-mcp-client`), which cannot
// render UI.
export const OPENAI_RENDER_UI_CLIENT_NAMES = ['openai-mcp'] as const
export type ClientCapabilities = {
// MCP `initialize` response includes an `instructions` field that most
// clients inject into the model's system prompt. Codex discards it, so
// we skip sending it (saving the payload cost) for those sessions.
supportsInstructions: boolean
}
export const DEFAULT_CLIENT_CAPABILITIES: ClientCapabilities = {
supportsInstructions: true,
}
type CapabilityOverride = {
// Matched against the self-reported `clientInfo.name`.
fragments: readonly string[]
// Matched against the User-Agent, for surfaces that omit `clientInfo.name`
// entirely — Codex through OpenAI's shared `openai-mcp` client identifies
// only via `openai-mcp/x.y.z (Codex)`.
userAgentFragments?: readonly string[]
capabilities: Partial<ClientCapabilities>
}
const CLIENT_CAPABILITY_OVERRIDES: readonly CapabilityOverride[] = [
{
fragments: ['codex'],
userAgentFragments: ['codex'],
capabilities: { supportsInstructions: false },
},
]
type MCPClientProfileInput = {
clientName?: string | undefined
clientVersion?: string | undefined
consumer?: string | undefined
oauthClientName?: string | undefined
// Per-request `x-anthropic-client` value (e.g. `ClaudeCode`, `ClaudeAI`).
// Anthropic pools MCP transports across products, so the live inner client
// can disagree with the session-pinned `clientName` from `initialize`.
vendorClient?: string | undefined
// Per-request `User-Agent` (e.g. `Claude-User` for Claude web/desktop).
userAgent?: string | undefined
uiSupported?: boolean | undefined
}
export class MCPClientProfile {
readonly clientName: string | undefined
readonly clientVersion: string | undefined
readonly consumer: string | undefined
readonly oauthClientName: string | undefined
readonly vendorClient: string | undefined
readonly userAgent: string | undefined
readonly uiSupported: boolean | undefined
private _capabilities: ClientCapabilities | undefined
constructor(input: MCPClientProfileInput) {
this.clientName = input.clientName
this.clientVersion = input.clientVersion
this.consumer = input.consumer
this.oauthClientName = input.oauthClientName
this.vendorClient = input.vendorClient
this.userAgent = input.userAgent
this.uiSupported = input.uiSupported
}
isToolsModeClient(): boolean {
// The only clients that auto-select the full per-tool roster; everyone
// else defaults to CLI (single-exec) mode — see `resolveMode`. Matched on
// the self-reported `clientInfo.name` and the User-Agent (older Cursor
// builds identify only through the UA); never on the vendor header, so
// Anthropic pooled transports can't land in tools mode.
return (
matchesAnyFragment(this.clientName, TOOLS_MODE_CLIENT_NAME_FRAGMENTS) ||
matchesAnyFragment(this.userAgent, TOOLS_MODE_USER_AGENT_FRAGMENTS)
)
}
isCliModeEnabled(): boolean {
// Gates dropping `structuredContent` when a `formatted_results` override
// is set — these clients read `content[].text`, so the structured copy
// would only bloat the payload. Every Anthropic product qualifies.
if (this.isAnthropicClient()) {
return true
}
// Otherwise fall back to the self-reported client name for coding agents.
return matchesAnyFragment(this.clientName, CODING_AGENT_CLIENT_NAME_FRAGMENTS)
}
isAnthropicClient(): boolean {
// Anthropic pools MCP transports across all its products (Claude Code,
// Claude.ai, Cowork, Claude Design, …), so the `x-anthropic-client` header
// is the reliable signal of the live product when present. Some surfaces
// (Claude.ai web/desktop, internal tools) connect without that header, so
// also accept the `Claude-User` user-agent and the pooled `Anthropic/…`
// `clientInfo.name`. Unlike `isRenderUiHost`, matching the pooled name here
// is safe and intended: every Anthropic product belongs in CLI mode, so
// there is nothing to misclassify.
return matchesAnyFragment(this.vendorClient, ANTHROPIC_CLIENT_NAME_FRAGMENTS) || this.isAnthropicConnector()
}
isAnthropicConnector(): boolean {
// The connector omits `x-anthropic-client` on `tools/list` and sends it on the call, so this must not read it.
return (
matchesAnyFragment(this.userAgent, ANTHROPIC_USER_AGENT_FRAGMENTS) ||
normalizeClientName(this.clientName ?? '').startsWith('anthropic')
)
}
isLegacyDialectOnly(): boolean {
return matchesAnyFragment(this.clientName, LEGACY_DIALECT_ONLY_CLIENT_NAME_FRAGMENTS)
}
isPostHogCodeConsumer(): boolean {
return this.consumer === POSTHOG_CODE_CONSUMER
}
isRenderUiHost(): boolean {
// A client that declares the MCP Apps extension states its own support, so the
// declaration wins over name detection in both directions. Clients that omit the
// extension fall back to the hosts known to render `render-ui`.
if (this.uiSupported !== undefined) {
return this.uiSupported
}
// The per-request vendor client (`x-anthropic-client`) is authoritative: it
// distinguishes the Claude surfaces that pool the same MCP transport —
// `ClaudeAI` (web/desktop) and `Cowork`, both `render-ui` hosts, from
// `ClaudeCode`, which only renders UI apps inline on the `exec` response
// (see `isInlineExecUiHost`). When it's present, trust it exclusively; only
// fall back to the user-agent and client name when the vendor header is
// absent. Otherwise a non-render-ui surface like Claude Code — which can
// share the `Claude-User` user-agent with web/desktop — would be
// misclassified as a UI host.
if (this.vendorClient) {
return matchesAnyFragment(this.vendorClient, ANTHROPIC_UI_HOST_VENDOR_FRAGMENTS)
}
return (
matchesAnyFragment(this.userAgent, ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS) ||
matchesProductName(this.userAgent, OPENAI_RENDER_UI_CLIENT_NAMES) ||
matchesProductName(this.clientName, OPENAI_RENDER_UI_CLIENT_NAMES)
)
}
isInlineExecUiHost(): boolean {
// Claude Code renders MCP UI apps inline on the single-exec `exec` tool, while
// Claude.ai and Cowork render through the separate `render-ui` tool.
// Like PostHog Desktop, Claude Code surfaces `structuredContent` to the model, so
// the exec UI-app branch suppresses it and re-homes the app data onto `_meta`.
// The per-request vendor header (`ClaudeCode`) is the reliable signal.
return matchesAnyFragment(this.vendorClient, INLINE_EXEC_UI_APP_VENDOR_FRAGMENTS)
}
isClaudeChatHost(): boolean {
// Same vendor-authoritative shape as `isRenderUiHost`, narrowed to the chat
// surfaces (Claude web/desktop) that ignore the `instructions` payload. The
// `Claude-User` user-agent fallback is kept for requests without the vendor
// header — those are predominantly chat sessions, and keeping env-context
// for a misattributed surface only costs payload size, not correctness.
if (this.vendorClient) {
return matchesAnyFragment(this.vendorClient, ANTHROPIC_CHAT_HOST_VENDOR_FRAGMENTS)
}
return matchesAnyFragment(this.userAgent, ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS)
}
get capabilities(): ClientCapabilities {
if (!this._capabilities) {
this._capabilities = this._resolveCapabilities()
}
return this._capabilities
}
private _resolveCapabilities(): ClientCapabilities {
const resolved: ClientCapabilities = { ...DEFAULT_CLIENT_CAPABILITIES }
for (const override of CLIENT_CAPABILITY_OVERRIDES) {
if (
matchesAnyFragment(this.clientName, override.fragments) ||
matchesAnyFragment(this.userAgent, override.userAgentFragments ?? [])
) {
Object.assign(resolved, override.capabilities)
}
}
return resolved
}
}
export function isCliModeEnabledClient(clientName: string | undefined): boolean {
return new MCPClientProfile({ clientName }).isCliModeEnabled()
}
export function isLegacyDialectOnlyClient(clientName: string | undefined): boolean {
return new MCPClientProfile({ clientName }).isLegacyDialectOnly()
}
export function isPostHogCodeConsumer(mcpConsumer: string | undefined): boolean {
return new MCPClientProfile({ consumer: mcpConsumer }).isPostHogCodeConsumer()
}
export function isToolsModeClient(clientName: string | undefined, userAgent?: string | undefined): boolean {
return new MCPClientProfile({ clientName, userAgent }).isToolsModeClient()
}