: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
import { RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps/server'
import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js'
import { hasScope } from '@/lib/api'
import { isPostHogCodeConsumer } from '@/lib/client-detection'
import type { QueryToolInfo } from '@/lib/instructions'
import { type InstructionsContext, InstructionsFormatter } from '@/lib/instructions-formatter'
import { isChatGptAppConnection } from '@/lib/oauth-constants'
import { formatPrompt } from '@/lib/utils'
import { RENDER_UI_RESOURCE_URI } from '@/resources/ui-apps.generated'
import { ProjectSkillCatalog } from '@/skills/project-skill-catalog'
import type { SkillCatalog } from '@/skills/skill-catalog'
import EXECUTE_SQL_PROMPT from '@/templates/execute-sql-prompt.md'
import CATALOG_TRUST_DISCOVERY from '@/templates/sections/catalog-trust-discovery.md'
import METRIC_DISCOVERY from '@/templates/sections/metric-discovery.md'
import SCHEMA_DISCOVERY from '@/templates/sections/schema-discovery.md'
import { EXEC_TOOL_ANNOTATIONS } from '@/tools/exec'
import { ExecLearnCatalog } from '@/tools/exec-learn'
import {
getRenderableToolNames,
makeRenderUiSchema,
RENDER_UI_TOOL_ANNOTATIONS,
RENDER_UI_TOOL_NAME,
RENDER_UI_TOOL_TITLE,
renderUiDescription,
} from '@/tools/render-ui'
import { getToolDefinition } from '@/tools/toolDefinitions'
import { trackSkillInvoked } from './analytics'
import { MCP_EXEC_SKILLS_FEATURE_FLAG, MCP_INBOX_FIRST_FLAG } from './constants'
import { getEffectiveMCPClientContext } from './mcp-context'
import type { ResolvedState } from './request-state-resolver'
import { toMcpInputSchema } from './tool-catalog'
export type ExecToolState = Pick<
ResolvedState,
| 'renderUiEnabled'
| 'businessKnowledgeContent'
| 'clientProfile'
| 'requestContext'
| 'sessionContext'
| 'toolFeatureFlags'
> & { allTools: readonly { name: string }[] }
/** Presence of this tool is the runtime signal that the notebook cell surface
* (the `revamped-py-notebooks` flag) is live for this client. */
const NOTEBOOK_ADD_CELL_TOOL = 'notebooks-add-cell'
const NOTEBOOK_RUN_TOOL = 'notebooks-run'
const DOCS_SEARCH_TOOL = 'docs-search'
const BUSINESS_KNOWLEDGE_SEARCH_TOOL = 'business-knowledge-documents-search'
const BUSINESS_KNOWLEDGE_REPO_SEARCH_TOOL = 'business-knowledge-repositories-search'
const INBOX_FIRST_TOOLS = ['inbox-reports-list', 'inbox-reports-retrieve']
const INBOX_CLAIM_TOOL = 'inbox-reports-claim'
// Human comment, not AI slop. Version 2.0.0 of the PostHog app for ChatGPT and Codex started
// requesting `llm_skill:read`, but existing connections never got re-prompted for it, so their
// agents hit a warning they can't act on. Telling them to "reconnect with that scope" doesn't
// work there, since the app picks the scopes, so this nudges them to the thing that does:
// disconnect the app and connect it again. Can be removed after 2027-01-01.
function projectSkillsScopeReason(oauthClientId: string | undefined): string {
if (isChatGptAppConnection(oauthClientId)) {
return 'This connection is missing the llm_skill:read scope. A new connection to the PostHog app includes it: disconnect the PostHog app in ChatGPT or Codex and connect it again to read project skills.'
}
return 'This connection is missing the llm_skill:read scope. Reconnect with that scope to read project skills.'
}
export class InstructionsBuilder {
private readonly formatter: InstructionsFormatter
private readonly guidelines: string
constructor(guidelines: string, formatter?: InstructionsFormatter) {
this.guidelines = guidelines
this.formatter = formatter ?? new InstructionsFormatter()
}
build(state: ResolvedState): string {
const supportsInstructions = state.clientProfile.capabilities.supportsInstructions
if (!supportsInstructions) {
return ''
}
const ctx = this.buildContext(state)
if (state.useSingleExec) {
return this.formatter.buildExecInstructions(ctx)
}
return this.formatter.buildToolsInstructions(ctx)
}
buildContext(state: ExecToolState): InstructionsContext {
return {
guidelines: this.guidelines,
tools: state.allTools.map((t) => ({
name: t.name,
category: getToolDefinition(t.name).category,
})),
queryTools: state.allTools
.filter((t) => t.name.startsWith('query-'))
.map((t) => {
const def = getToolDefinition(t.name)
return {
name: t.name,
title: def.title,
...(def.system_prompt_hint ? { systemPromptHint: def.system_prompt_hint } : {}),
} as QueryToolInfo
}),
renderUiEnabled: state.renderUiEnabled,
notebookCellsEnabled: state.allTools.some((tool) => tool.name === NOTEBOOK_ADD_CELL_TOOL),
notebookRunEnabled: state.allTools.some((tool) => tool.name === NOTEBOOK_RUN_TOOL),
docsSearchEnabled: state.allTools.some((tool) => tool.name === DOCS_SEARCH_TOOL),
businessKnowledgeContent: state.businessKnowledgeContent,
inboxFirstEnabled:
state.toolFeatureFlags?.[MCP_INBOX_FIRST_FLAG] === true &&
INBOX_FIRST_TOOLS.every((name) => state.allTools.some((tool) => tool.name === name)),
inboxClaimEnabled: state.allTools.some((tool) => tool.name === INBOX_CLAIM_TOOL),
}
}
buildExecToolEntry(state: ExecToolState): McpTool {
const commandReference = this.buildExecCommandReference(state)
const ExecSchema = { command: { type: 'string', description: commandReference } }
return {
name: 'exec',
title: 'Execute PostHog command',
description: this.buildExecToolDescription(state),
inputSchema: { type: 'object', properties: ExecSchema, required: ['command'] },
annotations: { ...EXEC_TOOL_ANNOTATIONS },
}
}
buildRenderUiToolEntry(tools: McpTool[]): McpTool | null {
const toolNames = getRenderableToolNames(tools)
if (toolNames.length === 0) {
return null
}
return {
name: RENDER_UI_TOOL_NAME,
title: RENDER_UI_TOOL_TITLE,
description: renderUiDescription(toolNames),
// OpenAI caches this schema across accounts; authorization stays in the executor.
inputSchema: toMcpInputSchema(makeRenderUiSchema(toolNames as [string, ...string[]])),
annotations: { ...RENDER_UI_TOOL_ANNOTATIONS },
// Advertise the umbrella UI resource so MCP Apps hosts (e.g. Claude) discover
// render-ui as renderable from `tools/list` and mount its iframe. Both the
// modern and legacy keys are emitted since this entry isn't normalized downstream.
_meta: {
ui: { resourceUri: RENDER_UI_RESOURCE_URI },
[RESOURCE_URI_META_KEY]: RENDER_UI_RESOURCE_URI,
},
}
}
buildExecCommandReference(state: ExecToolState): string {
// Claude web/desktop never show `instructions` to the model, so their reference carries the domain index.
const { guidesEnabled, skillsEnabled } = this.getExecLearnCapabilities(state)
const ctx = this.buildContext(state)
if (state.clientProfile.isClaudeChatHost()) {
return this.formatter.buildClaudeExecCommandReference(ctx, {
learnEnabled: guidesEnabled || skillsEnabled,
skillsEnabled,
})
}
return this.formatter.buildExecCommandReference(ctx, { learnEnabled: skillsEnabled })
}
buildExecLearnCatalog(state: ResolvedState, skills: SkillCatalog | undefined): ExecLearnCatalog | undefined {
const { guidesEnabled, skillsEnabled } = this.getExecLearnCapabilities(state)
if (!guidesEnabled && !skillsEnabled) {
return undefined
}
const guides = guidesEnabled ? this.formatter.buildClaudeExecLearnGuides(this.buildContext(state)) : []
const canReadProjectSkills = skillsEnabled && hasScope(state.apiKeyScopes, 'llm_skill:read')
// The catalog (and this closure) is rebuilt per request, so this Set dedupes
// within one exec command — a 5-file batch of one skill fires a single event,
// while separate commands each still count.
const invokedIdentifiers = new Set<string>()
return new ExecLearnCatalog(
guides,
skillsEnabled
? {
posthog: skills,
project: canReadProjectSkills ? new ProjectSkillCatalog(state.context) : undefined,
projectUnavailableReason: canReadProjectSkills
? undefined
: projectSkillsScopeReason(state.oauthClientId),
}
: undefined,
(invocation) => {
const identifier = `${invocation.source}:${invocation.skill}`
if (invokedIdentifiers.has(identifier)) {
return
}
invokedIdentifiers.add(identifier)
void trackSkillInvoked(state, invocation)
}
)
}
buildExecToolDescription(state?: ExecToolState): string {
const skillsEnabled = state ? this.getExecLearnCapabilities(state).skillsEnabled : false
const docsSearchEnabled = state?.allTools.some(({ name }) => name === DOCS_SEARCH_TOOL)
const businessKnowledgeSearchEnabled = state?.allTools.some(
({ name }) => name === BUSINESS_KNOWLEDGE_SEARCH_TOOL
)
const businessKnowledgeRepoSearchEnabled = state?.allTools.some(
({ name }) => name === BUSINESS_KNOWLEDGE_REPO_SEARCH_TOOL
)
return this.formatter.buildExecToolDescription({
skillsEnabled,
docsSearchEnabled,
businessKnowledgeSearchEnabled,
businessKnowledgeRepoSearchEnabled,
businessKnowledgeContent: state?.businessKnowledgeContent,
})
}
execSkillsEnabled(state: ExecToolState): boolean {
return this.getExecLearnCapabilities(state).skillsEnabled
}
getGuidelines(): string {
return this.guidelines
}
formatExecuteSqlDescription(): string {
// Metric discovery leads the splice so catalog-first routing still precedes
// raw schema discovery, without displacing the tool's own intro line.
const schemaDiscovery = `${METRIC_DISCOVERY.trim()}\n\n${SCHEMA_DISCOVERY.trim()}\n\n${CATALOG_TRUST_DISCOVERY.trim()}`
return formatPrompt(EXECUTE_SQL_PROMPT, {
guidelines: this.guidelines.trim(),
schema_discovery: schemaDiscovery,
})
}
private getExecLearnCapabilities(state: ExecToolState): { guidesEnabled: boolean; skillsEnabled: boolean } {
const clientContext = getEffectiveMCPClientContext(state.requestContext, state.sessionContext)
// The plugin and PostHog Code sandboxes bundle their own skill context, so
// learn stays off for them regardless of the feature flag.
if (clientContext.mcpConsumer === 'plugin' || isPostHogCodeConsumer(clientContext.mcpConsumer)) {
return { guidesEnabled: false, skillsEnabled: false }
}
// The connector's header-less `tools/list` advertises guides to every surface, so the call serves them too.
const { clientProfile } = state
return {
guidesEnabled: clientProfile.isClaudeChatHost() || clientProfile.isAnthropicConnector(),
skillsEnabled: state.toolFeatureFlags?.[MCP_EXEC_SKILLS_FEATURE_FLAG] === true,
}
}
}