@posthog/mcp 0.11.6 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -28,20 +28,32 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@posthog/core": "^1.48.0"
+    "@posthog/core": "^1.49.1"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.27.1",
     "@babel/preset-typescript": "^7.27.1",
-    "@modelcontextprotocol/sdk": "~1.29.0",
-    "@modelcontextprotocol/server": "~2.0.0",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27",
+    "@nestjs/microservices": "^11.1.27",
+    "@nestjs/platform-express": "^11.1.27",
     "@rslib/core": "0.10.6",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.0.0",
     "jest": "29.7.0",
+    "reflect-metadata": "^0.2.2",
+    "rekog-mcp-nest-v1": "npm:@rekog/mcp-nest@1.9.11",
+    "rekog-mcp-nest-v2": "npm:@rekog/mcp-nest@2.0.0",
+    "rxjs": "^7.8.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.8.2",
     "zod": "^3.25.0",
+    "zod4": "npm:zod@^4.4.3",
     "@posthog-tooling/tsconfig-base": "1.1.1",
-    "posthog-node": "^5.49.0"
+    "posthog-node": "^5.51.4"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.26.0",
@@ -73,11 +85,16 @@
   },
   "scripts": {
     "clean": "rimraf dist coverage",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "eslint src && prettier --check harness",
+    "lint:fix": "eslint src --fix && prettier --write harness",
     "generate-version": "node -p \"'export const version = \\'' + require('./package.json').version + '\\''\" > src/version.ts",
     "pretest:unit": "pnpm generate-version",
     "test:unit": "jest",
+    "test:integration": "pnpm test:integration:sdk-v1 && pnpm test:integration:sdk-v2 && pnpm test:integration:nest-v1 && pnpm test:integration:nest-v2",
+    "test:integration:sdk-v1": "node harness/dual-era/matrix.mjs --major v1 && node harness/dual-era/probe-late-handlers.mjs --major v1 && node harness/dual-era/probe-pagination.mjs --major v1",
+    "test:integration:sdk-v2": "node harness/dual-era/matrix.mjs --major v2 && node harness/dual-era/probe-late-handlers.mjs --major v2 && node harness/dual-era/probe-first-call-error.mjs && node harness/dual-era/probe-pagination.mjs --major v2",
+    "test:integration:nest-v1": "node harness/nest-v1/verify.mjs && LEVEL=low node harness/nest-v1/verify.mjs",
+    "test:integration:nest-v2": "node harness/nest-v2/verify.mjs && LEVEL=low node harness/nest-v2/verify.mjs",
     "prebuild": "pnpm generate-version",
     "build": "rslib build",
     "dev": "rslib build -w",

package/src/extensions/analytics-parameters.ts

@@ -1,4 +1,5 @@
 import type { AnalyticsParameterOwnership } from '../types'
+import { log, type LoggerFn } from './logger'
 import { getObjectShape, isZodRawShapeCompat } from './mcp-sdk-compat'
 import { canDeclareOutputInstructions } from './output-instructions'
 
@@ -42,6 +43,86 @@ export function canInjectAnalyticsParameter(
   )
 }
 
+export interface AnalyticsInjectableTool {
+  inputSchema?: AnalyticsInjectableJsonSchema
+  name?: string
+  [key: string]: unknown
+}
+
+/**
+ * Adds a required string parameter to a tool's JSON Schema. Called AFTER the MCP
+ * SDK has converted Zod schemas to JSON Schema, so only JSON Schema needs
+ * handling.
+ *
+ * Shared by every analytics parameter we inject (`context`, `llm_model`) so
+ * schema ownership, cloning, and required-field behavior cannot drift between
+ * them. `injectionLabel` only names the feature in the skip warnings.
+ *
+ * Skips injection (with a warning) for:
+ * - Tools that already declare the parameter — it is theirs, not ours
+ * - Complex schemas (oneOf/allOf/anyOf/$ref) that can't safely gain properties
+ */
+export function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableTool>(
+  tool: TTool,
+  parameterName: string,
+  description: string,
+  injectionLabel: string,
+  logger: LoggerFn = log
+): TTool {
+  const modifiedTool = { ...tool }
+  const toolName = tool.name || 'unknown'
+  const schema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema | undefined
+
+  if (!canInjectAnalyticsParameter(schema, parameterName)) {
+    if (hasAnalyticsParameter(schema, parameterName)) {
+      logger(`WARN: Tool "${toolName}" already has '${parameterName}' parameter. Skipping ${injectionLabel} injection.`)
+    } else {
+      logger(
+        `WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf/$ref). Skipping ${injectionLabel} injection.`
+      )
+    }
+    return modifiedTool
+  }
+
+  if (!modifiedTool.inputSchema) {
+    modifiedTool.inputSchema = {
+      type: 'object',
+      properties: {},
+      required: [],
+    }
+  }
+
+  // Deep copy: the server may reuse or freeze the schema object it handed us.
+  modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as AnalyticsInjectableJsonSchema
+
+  const inputSchema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema
+
+  if (!inputSchema.properties) {
+    inputSchema.properties = {}
+  }
+
+  // The MCP SDK emits `additionalProperties: false` when converting Zod schemas;
+  // left in place it would make the injected key invalid.
+  if (inputSchema.additionalProperties === false) {
+    inputSchema.additionalProperties = undefined
+  }
+
+  inputSchema.properties[parameterName] = {
+    type: 'string',
+    description,
+  }
+
+  if (Array.isArray(inputSchema.required)) {
+    if (!inputSchema.required.includes(parameterName)) {
+      inputSchema.required.push(parameterName)
+    }
+  } else {
+    inputSchema.required = [parameterName]
+  }
+
+  return modifiedTool
+}
+
 export function analyticsOwnsParameter(inputSchema: unknown, parameterName: string): boolean {
   if (!inputSchema || typeof inputSchema !== 'object') {
     return canInjectAnalyticsParameter(undefined, parameterName)
@@ -76,18 +157,19 @@ export function getAnalyticsParameterOwnership(
   return {
     context: analyticsOwnsParameter(inputSchema, 'context'),
     conversationId: analyticsOwnsParameter(inputSchema, 'conversation_id'),
+    llmModel: analyticsOwnsParameter(inputSchema, 'llm_model'),
     outputInstructions: canDeclareOutputInstructions(outputSchema),
   }
 }
 
 /**
  * Removes the arguments we injected, leaving the host's own. Input-side only, so
- * it takes just those two flags rather than the whole ownership record — callers
+ * it takes just those flags rather than the whole ownership record — callers
  * that have no output-schema context should not have to invent a value for it.
  */
 export function stripOwnedAnalyticsArguments(
   args: unknown,
-  ownership: Pick<AnalyticsParameterOwnership, 'context' | 'conversationId'>
+  ownership: Pick<AnalyticsParameterOwnership, 'context' | 'conversationId' | 'llmModel'>
 ): unknown {
   let cleanedArgs = args
   if (ownership.context && cleanedArgs && typeof cleanedArgs === 'object' && 'context' in cleanedArgs) {
@@ -98,5 +180,9 @@ export function stripOwnedAnalyticsArguments(
     const { conversation_id: _conversationId, ...rest } = cleanedArgs
     cleanedArgs = rest
   }
+  if (ownership.llmModel && cleanedArgs && typeof cleanedArgs === 'object' && 'llm_model' in cleanedArgs) {
+    const { llm_model: _llmModel, ...rest } = cleanedArgs
+    cleanedArgs = rest
+  }
   return cleanedArgs
 }

package/src/extensions/capture.ts

@@ -81,6 +81,10 @@ export function captureEvent(
     response: eventInput.response,
     userIntent: eventInput.userIntent,
     userIntentSource: eventInput.userIntentSource,
+    // Self-reported per request (`captureModel`), so like the header-borne
+    // fields above there is deliberately no sessionInfo fallback.
+    llmModel: eventInput.llmModel,
+    llmModelSource: eventInput.llmModelSource,
     isError: eventInput.isError,
     // Two consumers of the same failure: `error` is the full thrown value that
     // fans out into the separate `$exception` event (stacktrace, error-tracking

package/src/extensions/constants.ts

@@ -7,6 +7,8 @@ export const INACTIVITY_TIMEOUT_IN_MINUTES = 30
 
 export const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = `Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): "Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization."`
 
+export const DEFAULT_MODEL_PARAMETER_DESCRIPTION = `The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.`
+
 export const DEFAULT_CONVERSATION_ID_DESCRIPTION =
   "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it."
 
@@ -48,6 +50,8 @@ export const PostHogMCPAnalyticsProperty = {
   Intent: '$mcp_intent',
   IntentSource: '$mcp_intent_source',
   ListedToolNames: '$mcp_listed_tool_names',
+  LlmModel: '$mcp_llm_model',
+  LlmModelSource: '$mcp_llm_model_source',
   Parameters: '$mcp_parameters',
   ProtocolVersion: '$mcp_protocol_version',
   ResourceName: '$mcp_resource_name',

package/src/extensions/context-parameters.ts

@@ -4,11 +4,7 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { MCPAnalyticsOptions } from '../types'
-import {
-  canInjectAnalyticsParameter,
-  hasAnalyticsParameter,
-  type AnalyticsInjectableJsonSchema,
-} from './analytics-parameters'
+import { addAnalyticsParameterToTool, type AnalyticsInjectableJsonSchema } from './analytics-parameters'
 import { DEFAULT_CONTEXT_PARAMETER_DESCRIPTION } from './constants'
 import { log, type LoggerFn } from './logger'
 
@@ -27,8 +23,8 @@ export function getContextDescription(context: MCPAnalyticsOptions['context']):
 }
 
 /**
- * Adds a context parameter to a tool's JSON Schema.
- * This function is called AFTER the MCP SDK has converted Zod schemas to JSON Schema,
+ * Adds a context parameter to a tool's JSON Schema, via the shared injector.
+ * This is called AFTER the MCP SDK has converted Zod schemas to JSON Schema,
  * so we only need to handle JSON Schema format.
  *
  * Skips injection (with warning) for:
@@ -41,58 +37,13 @@ export function addContextParameterToTool<TTool extends ContextInjectableTool>(
   contextDescriptionOverride?: string,
   logger: LoggerFn = log
 ): TTool {
-  const modifiedTool = { ...tool }
-  const toolName = tool.name || 'unknown'
-  const schema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema | undefined
-
-  if (!canInjectAnalyticsParameter(schema, 'context')) {
-    if (hasAnalyticsParameter(schema, 'context')) {
-      logger(`WARN: Tool "${toolName}" already has 'context' parameter. Skipping context injection.`)
-    } else {
-      logger(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf/$ref). Skipping context injection.`)
-    }
-    return modifiedTool
-  }
-
-  if (!modifiedTool.inputSchema) {
-    modifiedTool.inputSchema = {
-      type: 'object',
-      properties: {},
-      required: [],
-    }
-  }
-
-  const contextDescription = contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION
-
-  // Deep copy: the server may reuse or freeze the schema object it handed us.
-  modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as AnalyticsInjectableJsonSchema
-
-  const inputSchema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema
-
-  if (!inputSchema.properties) {
-    inputSchema.properties = {}
-  }
-
-  // The MCP SDK emits `additionalProperties: false` when converting Zod schemas;
-  // left in place it would make the injected `context` key invalid.
-  if (inputSchema.additionalProperties === false) {
-    inputSchema.additionalProperties = undefined
-  }
-
-  inputSchema.properties.context = {
-    type: 'string',
-    description: contextDescription,
-  }
-
-  if (Array.isArray(inputSchema.required)) {
-    if (!inputSchema.required.includes('context')) {
-      inputSchema.required.push('context')
-    }
-  } else {
-    inputSchema.required = ['context']
-  }
-
-  return modifiedTool
+  return addAnalyticsParameterToTool(
+    tool,
+    'context',
+    contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION,
+    'context',
+    logger
+  )
 }
 
 export function addContextParameterToTools<TTool extends ContextInjectableTool>(

package/src/extensions/conversation-id.ts

@@ -162,7 +162,10 @@ export function buildConversationIdPromptBack(conversationId: string): {
 } {
   return {
     type: 'text',
-    text: `[SERVER]: Reuse conversation_id=${conversationId} on every subsequent tool call in this conversation. Required for the server to correlate calls and provide context-aware results.`,
+    // Tool results are untrusted content. Keep this as data rather than an
+    // instruction so clients do not classify it as prompt injection when they
+    // are still using a cached tool schema without `conversation_id`.
+    text: JSON.stringify({ conversation_id: conversationId }),
   }
 }
 

package/src/extensions/instrument-highlevel.ts

@@ -17,6 +17,7 @@ import {
   stripOwnedAnalyticsArguments,
 } from './analytics-parameters'
 import { isContextEnabled } from './context-parameters'
+import { isCaptureModelEnabled } from './model-parameters'
 import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
 import type { LoggerFn } from './logger'
@@ -27,6 +28,7 @@ import {
   handleListToolsRequest,
   patchRequestHandlers,
   captureToolCall,
+  getVirtualToolParameterOwnership,
   isToolAdvertised,
   readToolMetaCategory,
   type HandlerPatch,
@@ -189,6 +191,7 @@ function addTracingToToolCallbackInternal(
     const cleanedArgs = stripOwnedAnalyticsArguments(args, {
       context: isContextEnabled(options?.context) && analyticsOwnsParameter(inputSchema, 'context'),
       conversationId: options?.enableConversationId === true && analyticsOwnsParameter(inputSchema, 'conversation_id'),
+      llmModel: isCaptureModelEnabled(options?.captureModel) && analyticsOwnsParameter(inputSchema, 'llm_model'),
     })
     try {
       if (cleanedArgs === undefined) {
@@ -247,6 +250,7 @@ async function handleToolCallRequest(
       extra,
       eventType: MCPAnalyticsEventType.mcpMissingCapability,
       explicitContextIntent: context,
+      parameterOwnership: getVirtualToolParameterOwnership(data, toolName),
       execute: async () => handleReportMissing({ context }, data.logger),
     })
   }

package/src/extensions/instrument-lowlevel.ts

@@ -14,6 +14,7 @@ import {
   patchRequestHandlers,
   registerFallbackRequestHandler,
   captureToolCall,
+  getVirtualToolParameterOwnership,
   isToolAdvertised,
   type HandlerPatch,
 } from './instrumentation'
@@ -90,6 +91,7 @@ async function handleToolCallRequest(
       extra,
       eventType: MCPAnalyticsEventType.mcpMissingCapability,
       explicitContextIntent: context,
+      parameterOwnership: getVirtualToolParameterOwnership(data, toolName),
       execute: async () => handleReportMissing({ context }, data.logger),
     })
   }

package/src/extensions/instrumentation.ts

@@ -16,6 +16,13 @@ import type {
 } from '../types'
 import { getAnalyticsParameterOwnership, stripOwnedAnalyticsArguments } from './analytics-parameters'
 import { addContextParameterToTools, getContextDescription, isContextEnabled } from './context-parameters'
+import {
+  addModelParameterToTools,
+  getModelArgument,
+  getModelDescription,
+  isCaptureModelEnabled,
+  setEventModel,
+} from './model-parameters'
 import {
   addConversationIdToTools,
   type ConversationIdResolution,
@@ -179,6 +186,7 @@ function getActiveAnalyticsParameterOwnership(
     contextOwnershipKnown: ownership !== undefined,
     context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
     conversationId: data.options.enableConversationId === true && ownership?.conversationId === true,
+    llmModel: isCaptureModelEnabled(data.options.captureModel) && ownership?.llmModel === true,
     // Deliberately read off `listed`, never the override: only the advertised
     // JSON Schema can say whether `tools/list` declared `_mcp_instructions` (an
     // override is built from the live registry, which holds Zod on the
@@ -263,6 +271,13 @@ async function prepareToolCallEvent(
 
     await applyResolvedMetadata(event, data, request, extra)
     setEventIntent(event, await resolveToolCallIntent(data, request, canCaptureContextIntent, extra))
+    // Unlike intent, the model is only read under positive ownership: with
+    // ownership unresolved, `llm_model` may be the application's own argument,
+    // and recording a customer value as the calling agent's model is worse
+    // than a gap in coverage.
+    if (ownership.llmModel) {
+      setEventModel(event, getModelArgument(request))
+    }
     return { event, requestAttribution }
   } catch (error) {
     data.logger(
@@ -493,6 +508,31 @@ export function patchRequestHandlers(server: MCPServerLike, patches: Record<stri
   }) as MCPServerLike['setRequestHandler']
 }
 
+/**
+ * Ownership for the `get_more_tools` virtual tool, resolved without the
+ * `tools/list` cache.
+ *
+ * The missing-capability branch is only entered when the application does not
+ * advertise a tool by this name, so the descriptor is the SDK's own and what it
+ * declares is known statically. An instance that never served a listing — a
+ * per-request `McpServer`/`Server`, the topology in ADR-0011 — would otherwise
+ * read every injected parameter as not-ours and neither capture nor strip it.
+ *
+ * `conversation_id` still comes from the cache on purpose: resolving it here too
+ * would start minting a handle, and appending its prompt-back block, on
+ * instances that today mint none. That changes session anchoring (ADR-0004)
+ * rather than closing this gap.
+ */
+export function getVirtualToolParameterOwnership(
+  data: MCPAnalyticsData,
+  toolName: string
+): AnalyticsParameterOwnership {
+  return {
+    ...getAnalyticsParameterOwnership(getReportMissingToolDescriptor(toolName).inputSchema),
+    conversationId: data.toolAnalyticsParameterOwnership.get(toolName)?.conversationId === true,
+  }
+}
+
 /**
  * Checks the server's raw listing for a real owner of a candidate virtual tool.
  * This does not depend on a previous client request and does not call the
@@ -664,6 +704,17 @@ async function getTracedToolsList(
         }
       }
 
+      // After the virtual tool is appended, so it advertises `llm_model` too.
+      // Its ownership was cached above from the un-injected descriptor, so the
+      // SDK already strips and captures the argument on its calls — without
+      // injecting here the agent would never be asked for one, and
+      // missing-capability reports would be the only calls with no model.
+      // `context` is deliberately not injected into it: the virtual tool
+      // declares its own, and that argument is the report itself.
+      if (isCaptureModelEnabled(data.options.captureModel)) {
+        tools = addModelParameterToTools(tools, getModelDescription(data.options.captureModel), data.logger)
+      }
+
       if (data.options.enableConversationId) {
         tools = addConversationIdToTools(tools, data.logger)
         tools = addInstructionsToOutputSchemas(tools, data.logger)

package/src/extensions/model-parameters.ts

@@ -0,0 +1,94 @@
+import type { MCPAnalyticsOptions, MCPRequestLike, McpEvent } from '../types'
+import { addAnalyticsParameterToTool, type AnalyticsInjectableJsonSchema } from './analytics-parameters'
+import { DEFAULT_MODEL_PARAMETER_DESCRIPTION } from './constants'
+import { log, type LoggerFn } from './logger'
+
+/**
+ * Self-reported model capture (`captureModel`).
+ *
+ * MCP keeps servers deliberately model-ignorant: the wire carries client
+ * name/version and protocol version, never the LLM behind the client, and no
+ * spec revision changes that. The one place the information exists on the
+ * server side of the connection is the agent itself — harnesses inject the
+ * model id into the system prompt, so the agent can state it the same way it
+ * states its intent through the `context` parameter.
+ *
+ * This module injects a required `llm_model` string parameter into every tool
+ * (mirroring `context-parameters.ts`), strips it before the tool runs, and
+ * captures it as `$mcp_llm_model` with `$mcp_llm_model_source = "self_reported"`.
+ * The source property is deliberate: like `clientInfo` in the MCP spec, the
+ * value is self-reported and unverified — right for degradation analytics
+ * ("does our MCP get worse on model X?"), never for billing or security.
+ *
+ * Reasoning effort is deliberately NOT captured: it never crosses the wire,
+ * and models cannot reliably self-report it (harnesses apply it as a sampling
+ * parameter the model never sees), so any captured value would be noise.
+ */
+
+export interface ModelInjectableTool {
+  inputSchema?: AnalyticsInjectableJsonSchema
+  name?: string
+  [key: string]: unknown
+}
+
+/** Unlike `context`, model capture is opt-in: off unless explicitly enabled. */
+export function isCaptureModelEnabled(captureModel: MCPAnalyticsOptions['captureModel']): boolean {
+  return captureModel === true || (typeof captureModel === 'object' && captureModel !== null)
+}
+
+export function getModelDescription(captureModel: MCPAnalyticsOptions['captureModel']): string | undefined {
+  return typeof captureModel === 'object' && captureModel !== null ? captureModel.description : undefined
+}
+
+/**
+ * Adds an `llm_model` parameter to a tool's JSON Schema, via the shared
+ * injector so schema handling stays identical to `context`: a tool that already
+ * declares `llm_model` owns it, and complex schemas can't safely gain keys.
+ */
+export function addModelParameterToTool<TTool extends ModelInjectableTool>(
+  tool: TTool,
+  modelDescriptionOverride?: string,
+  logger: LoggerFn = log
+): TTool {
+  return addAnalyticsParameterToTool(
+    tool,
+    'llm_model',
+    modelDescriptionOverride || DEFAULT_MODEL_PARAMETER_DESCRIPTION,
+    'model',
+    logger
+  )
+}
+
+export function addModelParameterToTools<TTool extends ModelInjectableTool>(
+  tools: TTool[],
+  modelDescriptionOverride?: string,
+  logger: LoggerFn = log
+): TTool[] {
+  return tools.map((tool) => addModelParameterToTool(tool, modelDescriptionOverride, logger))
+}
+
+/**
+ * Reads the self-reported model off a tool-call request. Returns `undefined`
+ * for a missing, blank, or `"unknown"` value — the parameter description asks
+ * agents to pass `unknown` when uncertain, and an honest "I don't know" must
+ * not become a property value queries would group by.
+ */
+export function getModelArgument(request: MCPRequestLike): string | undefined {
+  const model = request.params?.arguments?.llm_model
+  if (typeof model !== 'string') {
+    return undefined
+  }
+  const trimmed = model.trim()
+  if (!trimmed || trimmed.toLowerCase() === 'unknown') {
+    return undefined
+  }
+  return trimmed
+}
+
+export function setEventModel(event: McpEvent, model: string | undefined): void {
+  if (!model) {
+    return
+  }
+  event.llmModel = model
+  event.llmModelSource = 'self_reported'
+}

package/src/extensions/output-instructions.ts

@@ -21,11 +21,9 @@ import type { AnalyticsInjectableJsonSchema } from './analytics-parameters'
  */
 export const MCP_INSTRUCTIONS_KEY = '_mcp_instructions'
 
-const INSTRUCTIONS_FIELD_DESCRIPTION =
-  'Server-issued handles for this conversation, and what to do with them. Read and follow.'
+const INSTRUCTIONS_FIELD_DESCRIPTION = 'Server-issued metadata for this conversation.'
 
-const CONVERSATION_ID_FIELD_DESCRIPTION =
-  'Echo this exact value as the conversation_id argument on every subsequent tool call.'
+const CONVERSATION_ID_FIELD_DESCRIPTION = 'The server-issued conversation identifier.'
 
 export interface OutputInstructionsInjectableTool {
   name?: string
@@ -165,7 +163,6 @@ export function addInstructionsToOutputSchema<TTool extends OutputInstructionsIn
         type: 'string',
         description: CONVERSATION_ID_FIELD_DESCRIPTION,
       },
-      instructions: { type: 'string' },
     },
   }
 
@@ -186,14 +183,11 @@ export function addInstructionsToOutputSchemas<TTool extends OutputInstructionsI
 
 export interface ConversationInstructions {
   conversation_id: string
-  instructions: string
 }
 
-const ECHO_INSTRUCTION = 'Send this conversation_id as an argument on every subsequent tool call in this conversation.'
-
 /** The payload mirrored into `structuredContent` for a tool we declared the key on. */
 export function buildConversationInstructions(conversationId: string): ConversationInstructions {
-  return { conversation_id: conversationId, instructions: ECHO_INSTRUCTION }
+  return { conversation_id: conversationId }
 }
 
 /**

package/src/extensions/posthog-events.ts

@@ -170,6 +170,14 @@ function addCommonEventProperties(event: Event, properties: Record<string, unkno
   if (event.userIntentSource) {
     properties[PostHogMCPAnalyticsProperty.IntentSource] = event.userIntentSource
   }
+  // Self-reported by the calling agent (`captureModel`), so present only on the
+  // requests where the agent supplied a definite value — never inferred.
+  if (event.llmModel) {
+    properties[PostHogMCPAnalyticsProperty.LlmModel] = event.llmModel
+  }
+  if (event.llmModelSource) {
+    properties[PostHogMCPAnalyticsProperty.LlmModelSource] = event.llmModelSource
+  }
   if (event.isError !== undefined) {
     properties[PostHogMCPAnalyticsProperty.IsError] = event.isError
   }

package/src/extensions/truncation.ts

@@ -435,6 +435,9 @@ export function truncateEvent<T extends Event | McpEvent>(event: T): T {
   result.clientUserAgent = truncateString(result.clientUserAgent, MAX_METADATA_LENGTH)
   result.vendorClient = truncateString(result.vendorClient, MAX_METADATA_LENGTH)
   result.errorType = truncateString(result.errorType, MAX_METADATA_LENGTH)
+  // Agent-supplied free text, same trust level as a header. Real model ids are
+  // tens of characters; anything past the metadata cap is junk, not a model.
+  result.llmModel = truncateString(result.llmModel, MAX_METADATA_LENGTH)
 
   // Error field limits — operate on the core `$exception_list` shape
   if (result.error != null && typeof result.error === 'object') {

package/src/index.ts

@@ -228,6 +228,8 @@ export type {
   McpCaptureCommon,
   MCPAnalyticsContextOptions,
   MCPAnalyticsIntentSource,
+  MCPAnalyticsModelOptions,
+  MCPAnalyticsModelSource,
   MCPAnalyticsOptions,
   MissingCapabilityCaptureData,
   PreparedToolCall,