@posthog/mcp 0.25.2 → 0.26.0

package/dist/version.js

@@ -27,7 +27,7 @@ var __webpack_require__ = {};
 })();
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
-const version = "0.25.2";
+const version = "0.26.0";
 __webpack_require__.d(__webpack_exports__, {}, {
     version: version
 });

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = "0.25.2";
+const version = "0.26.0";
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -54,8 +54,8 @@
     "zod4": "npm:zod@^4.4.3",
     "@vitest/coverage-v8": "^1.6.1",
     "vitest": "^1.6.1",
-    "@posthog-tooling/tsconfig-base": "1.1.1",
-    "posthog-node": "^5.63.1"
+    "posthog-node": "^5.63.1",
+    "@posthog-tooling/tsconfig-base": "1.1.1"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.26.0",

package/src/extensions/analytics-parameters.ts

@@ -50,7 +50,7 @@ export interface AnalyticsInjectableTool {
 }
 
 /**
- * Adds a required string parameter to a tool's JSON Schema. Called AFTER the MCP
+ * Adds a 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.
  *
@@ -67,6 +67,7 @@ export function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableToo
   parameterName: string,
   description: string,
   injectionLabel: string,
+  required: boolean,
   logger: LoggerFn = log
 ): TTool {
   const modifiedTool = { ...tool }
@@ -85,11 +86,7 @@ export function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableToo
   }
 
   if (!modifiedTool.inputSchema) {
-    modifiedTool.inputSchema = {
-      type: 'object',
-      properties: {},
-      required: [],
-    }
+    modifiedTool.inputSchema = { type: 'object', properties: {} }
   }
 
   // Deep copy: the server may reuse or freeze the schema object it handed us.
@@ -112,12 +109,11 @@ export function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableToo
     description,
   }
 
-  if (Array.isArray(inputSchema.required)) {
-    if (!inputSchema.required.includes(parameterName)) {
-      inputSchema.required.push(parameterName)
+  if (required) {
+    const existing = Array.isArray(inputSchema.required) ? inputSchema.required : []
+    if (!existing.includes(parameterName)) {
+      inputSchema.required = [...existing, parameterName]
     }
-  } else {
-    inputSchema.required = [parameterName]
   }
 
   return modifiedTool

package/src/extensions/capture.ts

@@ -42,7 +42,7 @@ export function captureEvent(
   const sessionInfo = requestAttribution ?? getSessionInfo(server, data, eventInput.sessionId)
 
   const duration =
-    eventInput.duration || (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : undefined)
+    eventInput.duration ?? (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : undefined)
 
   const fullEvent: McpEvent = {
     id: eventInput.id || '',

package/src/extensions/constants.ts

@@ -5,7 +5,7 @@
 
 export const INACTIVITY_TIMEOUT_IN_MINUTES = 30
 
-export const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = `Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution."`
+export const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = `A few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details.`
 
 export const DEFAULT_MODEL_PARAMETER_DESCRIPTION = `The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Pass "unknown" if you are not certain. Recorded for the server developer's analytics.`
 
@@ -36,6 +36,7 @@ export const PostHogMCPAnalyticsEvent = {
   ResourcesList: '$mcp_resources_list',
   ToolCall: '$mcp_tool_call',
   ToolsList: '$mcp_tools_list',
+  UnknownTool: '$mcp_unknown_tool',
 } as const
 
 export type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof typeof PostHogMCPAnalyticsEvent]

package/src/extensions/context-parameters.ts

@@ -42,6 +42,7 @@ export function addContextParameterToTool<TTool extends ContextInjectableTool>(
     'context',
     contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION,
     'context',
+    true,
     logger
   )
 }

package/src/extensions/event-types.ts

@@ -21,6 +21,7 @@ export const MCPAnalyticsEventType = {
   mcpResourcesRead: 'mcp:resources/read',
   mcpToolsCall: 'mcp:tools/call',
   mcpToolsList: 'mcp:tools/list',
+  mcpUnknownTool: 'mcp:unknown_tool',
 } as const
 
 export type MCPAnalyticsEventType = (typeof MCPAnalyticsEventType)[keyof typeof MCPAnalyticsEventType]

package/src/extensions/feedback.ts

@@ -12,6 +12,7 @@ import type {
 import { PostHogMCPAnalyticsProperty } from './constants'
 import { log, type LoggerFn } from './logger'
 import { sanitizeFreeText, sanitizeFreeTextValue } from './mcp-payloads'
+import { VIRTUAL_TOOL_ANNOTATIONS } from './tools'
 import { TRUNCATION_SUFFIX } from './truncation'
 
 export const SEND_FEEDBACK_TOOL_NAME = 'send_feedback' as const
@@ -150,16 +151,7 @@ export function getFeedbackToolDescriptor(options: CollectFeedbackOptions = {}):
       },
       required: ['feedback_type', 'summary', ...extraRequired],
     },
-    annotations: {
-      title: 'Send feedback',
-      readOnlyHint: true,
-      // Interacts with an external entity: the report lands in analytics.
-      openWorldHint: true,
-      // Only records the feedback, so repeat calls are harmless — and advertising
-      // it as idempotent makes agents more willing to call it proactively.
-      idempotentHint: true,
-      destructiveHint: false,
-    },
+    annotations: { ...VIRTUAL_TOOL_ANNOTATIONS },
   }
 }
 

package/src/extensions/instrument-highlevel.ts

@@ -30,7 +30,7 @@ import { isCaptureModelEnabled } from './model-parameters'
 import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
 import type { LoggerFn } from './logger'
-import { createWrappedTool, getToolFunction, hasToolFunction } from './mcp-sdk-compat'
+import { createWrappedTool, getToolFunction, hasToolFunction, readRequestHandlerMethod } from './mcp-sdk-compat'
 import { getReportMissingToolDescriptor, handleReportMissing, resolveMissingCapabilityToolName } from './tools'
 import {
   handleInitializeRequest,
@@ -236,7 +236,8 @@ async function handleToolCallRequest(
   originalCallToolHandler: MCPRequestHandler,
   request: MCPRequest,
   extra: MCPRequestExtra,
-  logger: LoggerFn
+  logger: LoggerFn,
+  registryDispatches: () => boolean
 ): Promise<unknown> {
   const data = getServerTrackingData(server)
   if (!data) {
@@ -284,7 +285,10 @@ async function handleToolCallRequest(
     })
   }
 
-  const registeredTool = toolName ? highLevelServer._registeredTools[toolName] : undefined
+  const registeredTool =
+    toolName && Object.prototype.hasOwnProperty.call(highLevelServer._registeredTools, toolName)
+      ? highLevelServer._registeredTools[toolName]
+      : undefined
 
   // Strip SDK-owned arguments before the MCP SDK validates the registered Zod
   // schema. The callback wrapper repeats the ownership-aware cleanup as a
@@ -299,6 +303,7 @@ async function handleToolCallRequest(
       ? getAnalyticsParameterOwnership(registeredTool.inputSchema, registeredTool.outputSchema)
       : undefined,
     inputSchema: registeredTool?.inputSchema,
+    isUnknownTool: !!toolName && !registeredTool && registryDispatches(),
     takeCapturedError: () => {
       const captured = extra?.__mcp_analytics_error
       if (extra) {
@@ -313,6 +318,7 @@ export function instrumentHighLevelServer(server: HighLevelMCPServerLike, logger
   try {
     const lowLevelServer = server.server
     const mcpAnalyticsData = getServerTrackingData(lowLevelServer)
+    const registryDispatches = trackRegistryDispatch(server)
 
     const handlers: Record<string, HandlerPatch> = {
       initialize: (trackedServer, originalHandler, request, extra) =>
@@ -320,7 +326,7 @@ export function instrumentHighLevelServer(server: HighLevelMCPServerLike, logger
       'tools/list': (trackedServer, originalHandler, request, extra) =>
         handleListToolsRequest(trackedServer, originalHandler, request, extra, logger),
       'tools/call': (trackedServer, originalHandler, request, extra) =>
-        handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger),
+        handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger, registryDispatches),
       'resources/list': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesList, logger),
       // Both listings publish `$mcp_resources_list`; the captured
       // `request.method` is what tells a static listing from a templated one.
@@ -342,6 +348,25 @@ export function instrumentHighLevelServer(server: HighLevelMCPServerLike, logger
   }
 }
 
+/**
+ * Whether the MCP SDK's own `tools/call` dispatcher, which reads `_registeredTools`,
+ * is the one serving calls. Adapters such as @rekog/mcp-nest bind their own
+ * dispatcher instead, and keep tools the registry never holds; on SDK v2 they
+ * replace the dispatcher the McpServer constructor installed.
+ */
+function trackRegistryDispatch(server: HighLevelMCPServerLike): () => boolean {
+  const lowLevelServer = server.server
+  let replaced = false
+  const setRequestHandler = lowLevelServer.setRequestHandler.bind(lowLevelServer) as (...args: unknown[]) => unknown
+  lowLevelServer.setRequestHandler = ((...args: unknown[]) => {
+    if (server._toolHandlersInitialized && readRequestHandlerMethod(args[0]) === 'tools/call') {
+      replaced = true
+    }
+    return setRequestHandler(...args)
+  }) as MCPServerLike['setRequestHandler']
+  return () => server._toolHandlersInitialized === true && !replaced
+}
+
 function seedToolDescriptionsFromRegistry(cache: Map<string, string>, tools: Record<string, RegisteredTool>): void {
   for (const [name, tool] of Object.entries(tools)) {
     if (typeof tool?.description === 'string') {

package/src/extensions/instrument-lowlevel.ts

@@ -132,7 +132,9 @@ async function handleToolCallRequest(
     })
   }
 
-  const originalTool = resolveOriginalTool(data, toolName)
+  const lookup = lookUpOriginalTool(data, toolName)
+  const originalTool = lookup.registered ? lookup.tool : undefined
+  const hasDispatcher = originalCallToolHandler !== undefined && originalCallToolHandler !== unknownToolHandler
   return await captureToolCall({
     server,
     data,
@@ -145,19 +147,23 @@ async function handleToolCallRequest(
         ? getAnalyticsParameterOwnership(originalTool.inputSchema)
         : undefined,
     inputSchema: originalTool?.inputSchema,
+    isUnknownTool: !!toolName && (!hasDispatcher || lookup.registered === false),
   })
 }
 
-function resolveOriginalTool(
-  data: MCPAnalyticsData,
-  toolName: string | undefined
-): { inputSchema?: unknown } | undefined {
-  if (!toolName || !data.options.resolveOriginalTool) return undefined
+type OriginalToolLookup =
+  | { registered: true; tool: { inputSchema?: unknown } }
+  | { registered: false }
+  | { registered: undefined }
+
+function lookUpOriginalTool(data: MCPAnalyticsData, toolName: string | undefined): OriginalToolLookup {
+  if (!toolName || !data.options.resolveOriginalTool) return { registered: undefined }
   try {
-    return data.options.resolveOriginalTool(toolName) ?? undefined
+    const tool = data.options.resolveOriginalTool(toolName)
+    return tool ? { registered: true, tool } : { registered: false }
   } catch (error) {
     data.logger(`Warning: resolveOriginalTool failed for tool ${toolName} - ${error}`)
-    return undefined
+    return { registered: undefined }
   }
 }
 

package/src/extensions/instrumentation.ts

@@ -128,6 +128,11 @@ interface TraceToolCallParams {
    * read it here to capture the real stack rather than the result envelope.
    */
   takeCapturedError?: () => unknown
+  /**
+   * The SDK knows the server has no tool by this name, so a rejected call is
+   * recorded as `$mcp_unknown_tool`, not as a tool call.
+   */
+  isUnknownTool?: boolean
 }
 
 /**
@@ -152,6 +157,7 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     extraEventProperties,
     omitCapturedParameters,
     takeCapturedError,
+    isUnknownTool,
   } = params
   const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall
   // The SDK's own virtual tools carry their intent in their own arguments, so
@@ -190,6 +196,7 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     resolvedEventType,
     canCaptureContextIntent
   )
+  const hostProperties = preparedEvent?.event.properties
   if (preparedEvent && resolvedEventType === MCPAnalyticsEventType.mcpToolsCall) {
     const sessionSchemas =
       (preparedEvent.event.sessionId ? data.toolInputSchemas.get(preparedEvent.event.sessionId) : undefined) ??
@@ -217,14 +224,25 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
   try {
     result = await execute(downstreamRequest)
   } catch (error) {
-    publishFailedToolEvent(server, preparedEvent, error, startTime, conversation, data.logger)
+    if (preparedEvent && conversation.minted) {
+      preparedEvent.event.conversationId = undefined
+    }
+    if (isUnknownTool) {
+      publishUnknownToolEvent(server, preparedEvent, hostProperties, data.logger)
+    } else {
+      publishFailedToolEvent(server, preparedEvent, error, startTime, data.logger)
+    }
     throw error
   }
 
   const finalResult = applyConversationInstructions(preparedEvent?.event ?? null, result, conversation, ownership)
-  // `result`, not `finalResult`: the error is read from what the tool produced,
-  // before the conversation handle was written into it. See below.
-  publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError, result)
+  if (isUnknownTool && isToolResultError(result)) {
+    publishUnknownToolEvent(server, preparedEvent, hostProperties, data.logger)
+  } else {
+    // `result`, not `finalResult`: the error is read from what the tool produced,
+    // before the conversation handle was written into it. See below.
+    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError, result)
+  }
   return finalResult
 }
 
@@ -469,7 +487,6 @@ function publishFailedToolEvent(
   preparedEvent: PreparedToolEvent | null,
   error: unknown,
   startTime: Date,
-  conversation: ConversationIdResolution,
   logger: LoggerFn
 ): void {
   if (!preparedEvent) {
@@ -477,9 +494,6 @@ function publishFailedToolEvent(
   }
   const { event, requestAttribution } = preparedEvent
   try {
-    if (conversation.minted) {
-      event.conversationId = undefined
-    }
     event.isError = true
     event.error = captureException(error)
     event.duration = Date.now() - startTime.getTime()
@@ -489,6 +503,44 @@ function publishFailedToolEvent(
   }
 }
 
+/**
+ * The agent asked for a tool the server does not have, so the call is not a
+ * tool call: only the requested name, identity, and session are recorded.
+ */
+function publishUnknownToolEvent(
+  server: MCPServerLike,
+  preparedEvent: PreparedToolEvent | null,
+  properties: McpEvent['properties'],
+  logger: LoggerFn
+): void {
+  if (!preparedEvent) {
+    return
+  }
+  const { event, requestAttribution } = preparedEvent
+  try {
+    captureEvent(
+      server,
+      {
+        eventType: MCPAnalyticsEventType.mcpUnknownTool,
+        timestamp: event.timestamp,
+        resourceName: event.resourceName,
+        sessionId: event.sessionId,
+        conversationId: event.conversationId,
+        clientName: event.clientName,
+        clientVersion: event.clientVersion,
+        protocolVersion: event.protocolVersion,
+        clientUserAgent: event.clientUserAgent,
+        vendorClient: event.vendorClient,
+        properties,
+      },
+      logger,
+      requestAttribution
+    )
+  } catch (publishError) {
+    logger(`Warning: PostHog MCP analytics failed to publish unknown tool event - ${publishError}`)
+  }
+}
+
 type ResourceEventType = typeof MCPAnalyticsEventType.mcpResourcesList | typeof MCPAnalyticsEventType.mcpResourcesRead
 
 interface TraceRequestParams {

package/src/extensions/model-parameters.ts

@@ -10,7 +10,7 @@ import { log, type LoggerFn } from './logger'
  * vendor metadata, while other harnesses inject the model id into the system
  * prompt so the agent can state it like intent through the `context` parameter.
  *
- * This module injects a required `llm_model` string parameter into every tool
+ * This module injects an optional `llm_model` string parameter into every tool
  * (mirroring `context-parameters.ts`), strips it before the tool runs, and
  * captures the best available value as `$mcp_llm_model`. Client metadata wins
  * over self-report, and `$mcp_llm_model_source` preserves that provenance.
@@ -54,6 +54,7 @@ export function addModelParameterToTool<TTool extends ModelInjectableTool>(
     'llm_model',
     modelDescriptionOverride || DEFAULT_MODEL_PARAMETER_DESCRIPTION,
     'model',
+    false,
     logger
   )
 }

package/src/extensions/posthog-events.ts

@@ -18,6 +18,7 @@ const BUILT_IN_EVENT_NAME_BY_TYPE = {
   [MCPAnalyticsEventType.mcpResourcesRead]: PostHogMCPAnalyticsEvent.ResourceRead,
   [MCPAnalyticsEventType.mcpToolsCall]: PostHogMCPAnalyticsEvent.ToolCall,
   [MCPAnalyticsEventType.mcpToolsList]: PostHogMCPAnalyticsEvent.ToolsList,
+  [MCPAnalyticsEventType.mcpUnknownTool]: PostHogMCPAnalyticsEvent.UnknownTool,
 } satisfies Record<MCPAnalyticsEventType, PostHogMCPAnalyticsEvent>
 
 function getDistinctId(event: Event): string {
@@ -121,7 +122,10 @@ function addPersonProcessingProperty(event: Event, properties: Record<string, un
 function addCommonEventProperties(event: Event, properties: Record<string, unknown>): void {
   if (event.resourceName) {
     properties[PostHogMCPAnalyticsProperty.ResourceName] = event.resourceName
-    if (event.eventType === MCPAnalyticsEventType.mcpToolsCall) {
+    if (
+      event.eventType === MCPAnalyticsEventType.mcpToolsCall ||
+      event.eventType === MCPAnalyticsEventType.mcpUnknownTool
+    ) {
       properties[PostHogMCPAnalyticsProperty.ToolName] = event.resourceName
     }
   }

package/src/extensions/posthog-mcp.ts

@@ -17,6 +17,7 @@ import type {
   PrepareToolListOptions,
   ToolCallCaptureData,
   ToolsListCaptureData,
+  UnknownToolCaptureData,
 } from '../types'
 import {
   buildFeedbackEventProperties,
@@ -54,7 +55,7 @@ import {
 } from './model-parameters'
 import { McpEventSink } from './sink'
 import { addInstructionsToOutputSchemas, mirrorInstructionsIntoStructuredContent } from './output-instructions'
-import { deriveSessionIdFromConversation } from './session'
+import { deriveSessionIdFromConversation, newSessionId } from './session'
 import { validateServerBuild } from './server-build'
 import { GET_MORE_TOOLS_NAME, getReportMissingToolDescriptor } from './tools'
 
@@ -479,6 +480,21 @@ export class PostHogMCP extends PostHog {
     this.#emit(event)
   }
 
+  /**
+   * Capture a call to a tool your server does not have. Emits
+   * `$mcp_unknown_tool`. Use it instead of {@link captureToolCall} when your
+   * dispatcher rejects the name, so the call is not counted as a tool call. A
+   * call that names no tool emits nothing.
+   */
+  captureUnknownTool(data: UnknownToolCaptureData): void {
+    if (!data.toolName) {
+      return
+    }
+    const event = baseEvent(MCPAnalyticsEventType.mcpUnknownTool, data)
+    event.resourceName = data.toolName
+    this.#emit(event)
+  }
+
   /**
    * Capture a `send_feedback` call as an agent-feedback report. Emits
    * `$mcp_feedback` with the report's `$mcp_feedback_*` properties and its
@@ -534,7 +550,7 @@ export class PostHogMCP extends PostHog {
 function baseEvent(eventType: MCPAnalyticsEventType, common: McpCaptureCommon): McpEvent {
   const event: McpEvent = {
     eventType,
-    sessionId: common.sessionId,
+    sessionId: common.sessionId || newSessionId(),
     conversationId: common.conversationId,
     protocolVersion: common.protocolVersion,
     // There is no `extra` on this path, so the host reads the request headers and

package/src/extensions/sanitization.ts

@@ -4,6 +4,7 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { ErrorProperties, Event, McpEvent } from '../types'
+import { MCPAnalyticsEventType } from './event-types'
 import { sanitizeCapturedValue, sanitizeFreeText } from './mcp-payloads'
 
 type SanitizedRecord = Record<string, unknown>
@@ -34,9 +35,13 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
 
   // Every event type, not just `resources/read`: the `$exception` sibling
   // carries the same name, and a tool or prompt name is free text an
-  // application can spell as a URL too.
+  // application can spell as a URL too. An unknown tool's name is whatever the
+  // agent typed, so it also gets the intent's personal-data redaction.
   if (result.resourceName != null) {
-    result.resourceName = sanitizeCapturedValue(result.resourceName) as string
+    result.resourceName =
+      result.eventType === MCPAnalyticsEventType.mcpUnknownTool
+        ? sanitizeFreeText(result.resourceName)
+        : (sanitizeCapturedValue(result.resourceName) as string)
   }
 
   // The intent comes straight from an agent-narrated `context` string, so it can

package/src/extensions/tools.ts

@@ -17,6 +17,18 @@ export function resolveMissingCapabilityToolName(options?: { missingCapabilityTo
   return options?.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
 }
 
+/**
+ * A virtual tool call sends one event to the server owner's PostHog project: it
+ * writes outside the conversation, overwrites nothing, records again on every
+ * repeat, and reaches nothing else.
+ */
+export const VIRTUAL_TOOL_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const
+
 type ReportMissingToolDescriptor = CompatibleToolsListLike['tools'][number]
 
 export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAME): ReportMissingToolDescriptor {
@@ -34,16 +46,7 @@ export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAM
       },
       required: ['context'],
     },
-    annotations: {
-      title: 'Get More Tools',
-      readOnlyHint: true,
-      // Interacts with an external entity: the report lands in analytics.
-      openWorldHint: true,
-      // Only records the gap, so repeat calls are harmless — and advertising it
-      // as idempotent makes agents more willing to call it proactively.
-      idempotentHint: true,
-      destructiveHint: false,
-    },
+    annotations: { ...VIRTUAL_TOOL_ANNOTATIONS },
   }
 }
 

package/src/extensions/truncation.ts

@@ -190,7 +190,7 @@ function truncateString(str: string | undefined, maxLength: number): string | un
   if (str.length <= maxLength) {
     return str
   }
-  return str.slice(0, maxLength) + TRUNCATION_SUFFIX
+  return str.slice(0, maxLength - TRUNCATION_SUFFIX.length) + TRUNCATION_SUFFIX
 }
 
 function truncateStackFrames(frames: StackFrame[] | undefined): StackFrame[] | undefined {

package/src/index.ts

@@ -271,6 +271,7 @@ export type {
   ToolCallCaptureData,
   ToolInputOptions,
   ToolsListCaptureData,
+  UnknownToolCaptureData,
   UserIdentity,
 } from './types'
 export type IdentifyFunction = MCPAnalyticsOptions['identify']

package/src/types.ts

@@ -224,8 +224,9 @@ export interface MCPAnalyticsOptions {
    * fresh instance per request strips them before the handler runs. Ownership
    * follows the same rule as a served listing: a Zod schema is read the way the
    * MCP SDK advertises it, and a host that lists its own JSON Schema returns that.
-   * Ownership learned from a listing on the instance wins. Ignored on a
-   * high-level `McpServer`, which reads its tool registry.
+   * Ownership learned from a listing on the instance wins. A rejected call to a
+   * tool this returns `undefined` for is recorded as `$mcp_unknown_tool`, not as
+   * a tool call. Ignored on a high-level `McpServer`, which reads its tool registry.
    */
   resolveOriginalTool?: (toolName: string) => { inputSchema?: unknown } | undefined
   /**
@@ -494,6 +495,8 @@ export interface ServerClientInfoLike {
 
 export interface HighLevelMCPServerLike {
   _registeredTools: { [name: string]: RegisteredTool }
+  /** Set once the MCP SDK has installed its own `tools/list` and `tools/call` handlers. */
+  _toolHandlersInitialized?: boolean
   registerTool?(name: string, config: { description?: string; inputSchema?: unknown }, handler: ToolCallback): void
   server: MCPServerLike
   tool?(name: string, cb: ToolCallback): void
@@ -848,6 +851,12 @@ export interface MissingCapabilityCaptureData extends McpCaptureCommon {
   parameters?: unknown
 }
 
+/** Payload for {@link PostHogMCP.captureUnknownTool}. Emits `$mcp_unknown_tool`. */
+export interface UnknownToolCaptureData extends McpCaptureCommon {
+  /** The tool name the agent asked for → `$mcp_tool_name`, sanitized as free text. */
+  toolName: string
+}
+
 /** Payload for {@link PostHogMCP.captureFeedback}. Emits `$mcp_feedback`. */
 export interface FeedbackCaptureData extends McpCaptureCommon {
   /**

package/src/version.ts

@@ -1 +1 @@
-export const version = "0.25.2"
+export const version = "0.26.0"