@posthog/mcp 0.15.0 → 0.16.1

package/src/extensions/instrument-highlevel.ts

@@ -11,6 +11,15 @@ import type {
   RegisteredTool,
   ToolCallback,
 } from '../types'
+import {
+  buildFeedbackEventProperties,
+  buildFeedbackIntent,
+  getFeedbackToolDescriptor,
+  handleFeedback,
+  parseFeedbackReport,
+  resolveCollectFeedbackOptions,
+  SEND_FEEDBACK_TOOL_NAME,
+} from './feedback'
 import {
   analyticsOwnsParameter,
   getAnalyticsParameterOwnership,
@@ -22,7 +31,7 @@ import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
 import type { LoggerFn } from './logger'
 import { createWrappedTool, getToolFunction, hasToolFunction } from './mcp-sdk-compat'
-import { handleReportMissing, resolveMissingCapabilityToolName } from './tools'
+import { getReportMissingToolDescriptor, handleReportMissing, resolveMissingCapabilityToolName } from './tools'
 import {
   handleInitializeRequest,
   handleListToolsRequest,
@@ -251,11 +260,39 @@ async function handleToolCallRequest(
       extra,
       eventType: MCPAnalyticsEventType.mcpMissingCapability,
       explicitContextIntent: context,
-      parameterOwnership: getVirtualToolParameterOwnership(data, toolName),
+      parameterOwnership: getVirtualToolParameterOwnership(
+        data,
+        toolName,
+        getReportMissingToolDescriptor(toolName).inputSchema
+      ),
       execute: async () => handleReportMissing({ context }, data.logger),
     })
   }
 
+  const feedbackOptions = resolveCollectFeedbackOptions(data.options.collectFeedback)
+  const isFeedbackCandidate =
+    feedbackOptions !== undefined && toolName === (feedbackOptions.toolName ?? SEND_FEEDBACK_TOOL_NAME)
+
+  if (isFeedbackCandidate && (await isToolAdvertised(server, toolName, extra, data.logger)) === false) {
+    const report = parseFeedbackReport(request.params?.arguments, feedbackOptions)
+    return await captureToolCall({
+      server,
+      data,
+      request,
+      extra,
+      eventType: MCPAnalyticsEventType.mcpFeedback,
+      explicitContextIntent: buildFeedbackIntent(report),
+      omitCapturedParameters: true,
+      extraEventProperties: buildFeedbackEventProperties(report),
+      parameterOwnership: getVirtualToolParameterOwnership(
+        data,
+        toolName,
+        getFeedbackToolDescriptor(feedbackOptions).inputSchema
+      ),
+      execute: async () => handleFeedback(report, feedbackOptions, data.logger),
+    })
+  }
+
   const registeredTool = toolName ? highLevelServer._registeredTools[toolName] : undefined
 
   // Strip SDK-owned arguments before the MCP SDK validates the registered Zod

package/src/extensions/instrument-lowlevel.ts

@@ -4,10 +4,19 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { CompatibleRequestHandlerExtra, MCPRequestLike, MCPServerLike } from '../types'
+import {
+  buildFeedbackEventProperties,
+  buildFeedbackIntent,
+  getFeedbackToolDescriptor,
+  handleFeedback,
+  parseFeedbackReport,
+  resolveCollectFeedbackOptions,
+  SEND_FEEDBACK_TOOL_NAME,
+} from './feedback'
 import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
 import type { LoggerFn } from './logger'
-import { handleReportMissing, resolveMissingCapabilityToolName } from './tools'
+import { getReportMissingToolDescriptor, handleReportMissing, resolveMissingCapabilityToolName } from './tools'
 import {
   handleInitializeRequest,
   handleListToolsRequest,
@@ -98,11 +107,39 @@ async function handleToolCallRequest(
       extra,
       eventType: MCPAnalyticsEventType.mcpMissingCapability,
       explicitContextIntent: context,
-      parameterOwnership: getVirtualToolParameterOwnership(data, toolName),
+      parameterOwnership: getVirtualToolParameterOwnership(
+        data,
+        toolName,
+        getReportMissingToolDescriptor(toolName).inputSchema
+      ),
       execute: async () => handleReportMissing({ context }, data.logger),
     })
   }
 
+  const feedbackOptions = resolveCollectFeedbackOptions(data.options.collectFeedback)
+  const isFeedbackCandidate =
+    feedbackOptions !== undefined && toolName === (feedbackOptions.toolName ?? SEND_FEEDBACK_TOOL_NAME)
+
+  if (isFeedbackCandidate && (await isToolAdvertised(server, toolName, extra, data.logger)) === false) {
+    const report = parseFeedbackReport(request.params?.arguments, feedbackOptions)
+    return await captureToolCall({
+      server,
+      data,
+      request,
+      extra,
+      eventType: MCPAnalyticsEventType.mcpFeedback,
+      explicitContextIntent: buildFeedbackIntent(report),
+      omitCapturedParameters: true,
+      extraEventProperties: buildFeedbackEventProperties(report),
+      parameterOwnership: getVirtualToolParameterOwnership(
+        data,
+        toolName,
+        getFeedbackToolDescriptor(feedbackOptions).inputSchema
+      ),
+      execute: async () => handleFeedback(report, feedbackOptions, data.logger),
+    })
+  }
+
   return await captureToolCall({
     server,
     data,

package/src/extensions/instrumentation.ts

@@ -7,6 +7,7 @@ import type {
   AnalyticsParameterOwnership,
   CompatibleRequestHandlerExtra,
   CompatibleToolsListLike,
+  JsonRecord,
   MCPAnalyticsData,
   MCPRequestLike,
   MCPServerLike,
@@ -44,6 +45,7 @@ import { readRequestHandlerMethod } from './mcp-sdk-compat'
 import { getRequestHeaders } from './request-headers'
 import { getSessionId, getSessionInfo, isModernEraRequest, newSessionId } from './session'
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from './session-token'
+import { getFeedbackToolDescriptor, resolveCollectFeedbackOptions, SEND_FEEDBACK_TOOL_NAME } from './feedback'
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from './tools'
 import { applyResolvedMetadata, isToolResultError } from './tracing-helpers'
 
@@ -70,16 +72,29 @@ interface TraceToolCallParams {
   parameterOwnership?: AnalyticsParameterOwnership
   /**
    * Event type to capture. Defaults to a tool call; the `get_more_tools` virtual
-   * tool passes `mcpMissingCapability` so it records a capability gap rather than
-   * a tool invocation.
+   * tool passes `mcpMissingCapability` and `send_feedback` passes
+   * `mcpFeedback`, so they record a capability gap / a feedback report
+   * rather than a tool invocation.
    */
   eventType?: MCPAnalyticsEventType
   /**
    * When set, used verbatim as the captured intent (source `context_parameter`)
-   * instead of running `resolveToolCallIntent`. Used by the `get_more_tools`
-   * virtual tool, which carries its intent in the `context` argument.
+   * instead of running `resolveToolCallIntent`. Used by the virtual tools, which
+   * carry their intent in their own arguments.
    */
   explicitContextIntent?: string
+  /**
+   * Extra event properties spread onto the captured event, after the host's
+   * `eventProperties`. Used by `send_feedback` for its `$mcp_feedback_*` fields.
+   */
+  extraEventProperties?: JsonRecord
+  /**
+   * Drop the generically captured `$mcp_parameters` from the event. Used by
+   * `send_feedback`: its arguments are agent-narrated free text, so the
+   * PII-redacted `$mcp_feedback_*` properties are the captured surface — the
+   * raw arguments would bypass that redaction and record undeclared fields.
+   */
+  omitCapturedParameters?: boolean
   /**
    * Optional accessor for an error the executor captured out-of-band. The
    * high-level SDK turns thrown tool errors into `isError: true` results before
@@ -107,21 +122,28 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     parameterOwnership,
     eventType,
     explicitContextIntent,
+    extraEventProperties,
+    omitCapturedParameters,
     takeCapturedError,
   } = params
   const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall
+  // The SDK's own virtual tools carry their intent in their own arguments, so
+  // the injected `context` parameter neither exists on them nor gets read.
+  const isVirtualAnalyticsTool =
+    resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability ||
+    resolvedEventType === MCPAnalyticsEventType.mcpFeedback
   const ownership = getActiveAnalyticsParameterOwnership(
     data,
     request.params?.name,
     parameterOwnership,
-    resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability
+    isVirtualAnalyticsTool
   )
   // Reading the argument and removing it are separate questions: deleting one the
   // application declared costs the customer their call, so the strip below still
   // requires positive ownership, while reading it when ownership is unresolved
   // costs at worst a mislabelled property. ADR-0011.
   const canCaptureContextIntent =
-    resolvedEventType !== MCPAnalyticsEventType.mcpMissingCapability &&
+    !isVirtualAnalyticsTool &&
     isContextEnabled(data.options.context) &&
     (ownership.context || !ownership.contextOwnershipKnown)
   const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments)
@@ -145,6 +167,12 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
   if (preparedEvent && explicitContextIntent) {
     setExplicitContextIntent(preparedEvent.event, explicitContextIntent)
   }
+  if (preparedEvent && extraEventProperties) {
+    preparedEvent.event.properties = { ...preparedEvent.event.properties, ...extraEventProperties }
+  }
+  if (preparedEvent && omitCapturedParameters) {
+    preparedEvent.event.parameters = undefined
+  }
 
   let result: unknown
   try {
@@ -178,13 +206,13 @@ function getActiveAnalyticsParameterOwnership(
   data: MCPAnalyticsData,
   toolName: string | undefined,
   override: AnalyticsParameterOwnership | undefined,
-  isMissingCapabilityTool: boolean
+  isVirtualAnalyticsTool: boolean
 ): ActiveAnalyticsParameterOwnership {
   const listed = toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : undefined
   const ownership = override ?? listed
   return {
     contextOwnershipKnown: ownership !== undefined,
-    context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
+    context: !isVirtualAnalyticsTool && 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
@@ -613,26 +641,31 @@ export function patchRequestHandlers(server: MCPServerLike, patches: Record<stri
 }
 
 /**
- * Ownership for the `get_more_tools` virtual tool, resolved without the
- * `tools/list` cache.
+ * Ownership for an SDK-owned virtual tool (`get_more_tools`, `send_feedback`),
+ * resolved from its own descriptor rather than 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.
+ * A virtual-tool 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.
+ *
+ * `virtualToolInputSchema` is required (not defaulted to one specific virtual
+ * tool's descriptor) so every call site names the tool it means; each caller
+ * passes its own descriptor's `inputSchema`.
  */
 export function getVirtualToolParameterOwnership(
   data: MCPAnalyticsData,
-  toolName: string
+  toolName: string,
+  virtualToolInputSchema: unknown
 ): AnalyticsParameterOwnership {
   return {
-    ...getAnalyticsParameterOwnership(getReportMissingToolDescriptor(toolName).inputSchema),
+    ...getAnalyticsParameterOwnership(virtualToolInputSchema),
     conversationId: data.toolAnalyticsParameterOwnership.get(toolName)?.conversationId === true,
   }
 }
@@ -808,6 +841,21 @@ async function getTracedToolsList(
         }
       }
 
+      const feedbackOptions = resolveCollectFeedbackOptions(data.options.collectFeedback)
+      if (feedbackOptions) {
+        const feedbackToolName = feedbackOptions.toolName ?? SEND_FEEDBACK_TOOL_NAME
+        const alreadyPresent = tools.some((tool) => tool?.name === feedbackToolName)
+        if (alreadyPresent) {
+          data.logger(
+            `Warning: Cannot inject agent-feedback tool "${feedbackToolName}" because a real tool already uses that name. The real tool will not be intercepted.`
+          )
+        } else {
+          const virtualTool = getFeedbackToolDescriptor(feedbackOptions)
+          tools.push(virtualTool)
+          cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, [virtualTool])
+        }
+      }
+
       // 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

package/src/extensions/mcp-payloads.ts

@@ -508,8 +508,8 @@ function sanitizeString(value: string): string {
 }
 
 /**
- * Sanitizes the agent-narrated intent: structured PII on top of the passes every
- * captured string gets.
+ * Sanitizes agent-narrated free text (`$mcp_intent`, the `send_feedback`
+ * fields): structured PII on top of the passes every captured string gets.
  *
  * Every step of the order is load-bearing. The binary gate reads the value as it
  * arrived, because splicing `[redacted]` into a blob — a Luhn-valid run inside
@@ -519,7 +519,7 @@ function sanitizeString(value: string): string {
  * URL pass, because the URL rewrite percent-encodes the `@` that the email
  * pattern anchors on.
  */
-export function sanitizeIntent(value: string): string {
+export function sanitizeFreeText(value: string): string {
   if (isBinaryBlob(value)) {
     return BINARY_REDACTED_VALUE
   }
@@ -607,16 +607,29 @@ export function redactPii(value: string): string {
 }
 
 export function sanitizeCapturedValue(value: unknown): unknown {
+  return sanitizeValueWith(value, sanitizeString)
+}
+
+/**
+ * {@link sanitizeCapturedValue} with the intent-grade string pass
+ * ({@link sanitizeFreeText}) on every string leaf, so nested agent-narrated
+ * values get structured-PII redaction in the load-bearing order too.
+ */
+export function sanitizeFreeTextValue(value: unknown): unknown {
+  return sanitizeValueWith(value, sanitizeFreeText)
+}
+
+function sanitizeValueWith(value: unknown, sanitizeStringFn: (value: string) => string): unknown {
   if (value == null) {
     return value
   }
 
   if (typeof value === 'string') {
-    return sanitizeString(value)
+    return sanitizeStringFn(value)
   }
 
   if (Array.isArray(value)) {
-    return value.map(sanitizeCapturedValue)
+    return value.map((item) => sanitizeValueWith(item, sanitizeStringFn))
   }
 
   if (value instanceof Date) {
@@ -629,7 +642,7 @@ export function sanitizeCapturedValue(value: unknown): unknown {
 
   const result: JsonRecord = {}
   for (const [key, nestedValue] of Object.entries(value)) {
-    result[key] = shouldRedactKey(key) ? REDACTED_VALUE : sanitizeCapturedValue(nestedValue)
+    result[key] = shouldRedactKey(key) ? REDACTED_VALUE : sanitizeValueWith(nestedValue, sanitizeStringFn)
   }
   return result
 }

package/src/extensions/posthog-events.ts

@@ -10,6 +10,7 @@ import { MCPAnalyticsEventType } from './event-types'
 const BUILT_IN_EVENT_NAME_BY_TYPE = {
   [MCPAnalyticsEventType.custom]: PostHogMCPAnalyticsEvent.Custom,
   [MCPAnalyticsEventType.identify]: PostHogMCPAnalyticsEvent.Identify,
+  [MCPAnalyticsEventType.mcpFeedback]: PostHogMCPAnalyticsEvent.Feedback,
   [MCPAnalyticsEventType.mcpMissingCapability]: PostHogMCPAnalyticsEvent.MissingCapability,
   [MCPAnalyticsEventType.mcpInitialize]: PostHogMCPAnalyticsEvent.Initialize,
   [MCPAnalyticsEventType.mcpPromptsGet]: PostHogMCPAnalyticsEvent.PromptGet,

package/src/extensions/posthog-mcp.ts

@@ -1,6 +1,9 @@
 import { PostHog, type PostHogOptions } from 'posthog-node'
 
 import type {
+  FeedbackCaptureData,
+  CollectFeedbackOptions,
+  CollectFeedbackConfig,
   InitializeCaptureData,
   JsonRecord,
   MCPAnalyticsOptions,
@@ -13,6 +16,14 @@ import type {
   ToolCallCaptureData,
   ToolsListCaptureData,
 } from '../types'
+import {
+  buildFeedbackEventProperties,
+  buildFeedbackIntent,
+  getFeedbackToolDescriptor,
+  parseFeedbackReport,
+  resolveCollectFeedbackOptions,
+  SEND_FEEDBACK_TOOL_NAME,
+} from './feedback'
 import { analyticsOwnsParameter, stripOwnedAnalyticsArguments } from './analytics-parameters'
 import {
   addContextParameterToTools,
@@ -47,6 +58,17 @@ export interface PostHogMCPOptions extends PostHogOptions {
    * can't drift. Defaults to `get_more_tools`.
    */
   missingCapabilityToolName?: string
+  /**
+   * Enable + configure the `send_feedback` virtual tool: injected by
+   * {@link PostHogMCP.prepareToolList} (when its `collectFeedback` toggle is on)
+   * and detected by {@link PostHogMCP.prepareToolCall}. Set once here so
+   * injection and detection can't drift — without this option, `prepareToolCall`
+   * never flags a call as feedback, so a real tool that uses the name is not
+   * shadowed. Pick a `toolName` no real tool uses. `onFeedback` is ignored on
+   * this path — the host dispatcher routes reports itself via
+   * {@link PreparedToolCall.feedbackReport}.
+   */
+  collectFeedback?: CollectFeedbackConfig
   /**
    * Capture the calling model from recognized client metadata, with an injected
    * `llm_model` argument as fallback. Off by default.
@@ -93,19 +115,36 @@ export interface PostHogMCPOptions extends PostHogOptions {
 export class PostHogMCP extends PostHog {
   readonly #sink = new McpEventSink(this)
 
-  // The get_more_tools name lives here (not on the per-call options) so that
+  // The virtual-tool config lives here (not on the per-call options) so that
   // prepareToolList (inject) and prepareToolCall (detect) always agree.
   readonly #missingCapabilityToolName: string
+  // `undefined` is the enable switch's off state: without it, prepareToolCall
+  // must never claim a call named like the virtual tool — the host may have a
+  // real tool by that name, and flagging it would shadow the real handler.
+  readonly #feedbackOptions: CollectFeedbackOptions | undefined
   readonly #captureModel: MCPAnalyticsOptions['captureModel']
   readonly #modelParameterOwnership = new Map<string, boolean>()
 
   constructor(apiKey: string, options: PostHogMCPOptions = {}) {
     super(apiKey, options)
     this.#missingCapabilityToolName = options.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
+    this.#feedbackOptions = resolveCollectFeedbackOptions(options.collectFeedback)
+    // Fail fast on a config error (reserved extra key, undeclared extraRequired)
+    // instead of first surfacing it when a tools/list is served.
+    getFeedbackToolDescriptor(this.#feedbackOptions)
+    if (this.#feedbackOptions?.onFeedback) {
+      log(
+        'Warning: collectFeedback.onFeedback is ignored on the PostHogMCP path - route reports from your dispatcher via prepareToolCall().feedbackReport instead.'
+      )
+    }
     this.#captureModel = options.captureModel
     applyMcpLibIdentity(this)
   }
 
+  get #feedbackToolName(): string {
+    return this.#feedbackOptions?.toolName ?? SEND_FEEDBACK_TOOL_NAME
+  }
+
   /** Capture a tool invocation. Emits `$mcp_tool_call` (+ an `$exception` sibling on error). */
   captureToolCall(data: ToolCallCaptureData): void {
     const event = baseEvent(MCPAnalyticsEventType.mcpToolsCall, data)
@@ -160,8 +199,9 @@ export class PostHogMCP extends PostHog {
    * Decorate your `tools/list` response with PostHog's analytics affordances:
    * injects the `context` argument into every tool (so agents state their intent,
    * captured as `$mcp_intent`), injects `llm_model` when the constructor's
-   * `captureModel` option is enabled, and appends `get_more_tools` when
-   * `reportMissing` is on. Returns a new array; your tools are untouched.
+   * `captureModel` option is enabled, appends `get_more_tools` when
+   * `reportMissing` is on, and appends `send_feedback` when `collectFeedback` is
+   * on. Returns a new array; your tools are untouched.
    *
    * The appended `get_more_tools` descriptor carries only the base MCP tool fields
    * (name, description, input schema) — not any framework-specific fields your
@@ -188,6 +228,14 @@ export class PostHogMCP extends PostHog {
       prepared = [...prepared, getReportMissingToolDescriptor(this.#missingCapabilityToolName) as TTool]
     }
 
+    if (
+      options.collectFeedback &&
+      this.#feedbackOptions !== undefined &&
+      !prepared.some((tool) => tool?.name === this.#feedbackToolName)
+    ) {
+      prepared = [...prepared, getFeedbackToolDescriptor(this.#feedbackOptions) as TTool]
+    }
+
     if (isCaptureModelEnabled(this.#captureModel)) {
       this.#modelParameterOwnership.clear()
       const ownershipByName = new Map<string, boolean>()
@@ -230,8 +278,12 @@ export class PostHogMCP extends PostHog {
    *
    * @example
    * ```ts
+   * const originalTool = myTools.find((tool) => tool.name === name)
    * const { intent, intentSource, llmModel, llmModelSource, args, isMissingCapability } =
-   *   posthog.prepareToolCall(name, rawArgs, { requestMeta: request.params?._meta })
+   *   posthog.prepareToolCall(name, rawArgs, {
+   *     originalTool,
+   *     requestMeta: request.params?._meta,
+   *   })
    * if (isMissingCapability) {
    *   posthog.captureMissingCapability({ context: intent, llmModel, llmModelSource, ...identity })
    *   return getMoreToolsResult()
@@ -256,6 +308,13 @@ export class PostHogMCP extends PostHog {
       ? resolveModel({ params: { arguments: args, _meta: options.requestMeta } }, ownsModel)
       : undefined
     const strippedArgs = stripContext(args)
+    // A supplied `originalTool` is a real application tool by this name (it
+    // comes from the host's own list, which never holds the virtual tool), so
+    // the real tool wins — the stateless twin of instrument()'s listing-derived
+    // collision handling. Without it the name match stands, and the documented
+    // remedy for a collision is configuring a non-colliding `toolName`.
+    const isFeedback =
+      this.#feedbackOptions !== undefined && name === this.#feedbackToolName && options.originalTool == null
     return {
       intent,
       intentSource: intent ? 'context_parameter' : undefined,
@@ -269,6 +328,8 @@ export class PostHogMCP extends PostHog {
           }) as Record<string, unknown> | undefined)
         : strippedArgs,
       isMissingCapability: name === this.#missingCapabilityToolName,
+      isFeedback,
+      feedbackReport: isFeedback ? parseFeedbackReport(args, this.#feedbackOptions) : undefined,
     }
   }
 
@@ -286,6 +347,26 @@ export class PostHogMCP extends PostHog {
     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
+   * summary/details as `$mcp_intent`. Reply to the agent with
+   * `sendFeedbackResult()` (or a custom text) after routing the report to your
+   * own feedback backend.
+   */
+  captureFeedback(data: FeedbackCaptureData): void {
+    const event = baseEvent(MCPAnalyticsEventType.mcpFeedback, data)
+    event.resourceName = this.#feedbackToolName
+    // Deliberately no `$mcp_parameters`: the arguments are agent-narrated free
+    // text, and the PII-redacted `$mcp_feedback_*` properties are the captured
+    // surface. Raw arguments would bypass that redaction. Feedback properties
+    // win over the caller's, matching the instrument() path's spread order.
+    event.properties = { ...event.properties, ...buildFeedbackEventProperties(data.report) }
+    applyIntent(event, buildFeedbackIntent(data.report), 'context_parameter')
+    setEventModel(event, data.llmModel, data.llmModelSource)
+    this.#emit(event)
+  }
+
   /**
    * Fire-and-forget, mirroring posthog-node's `capture()`: the event is enqueued
    * on the client, not awaited. Never throws — a failure to record analytics

package/src/extensions/sanitization.ts

@@ -4,7 +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 { sanitizeCapturedValue, sanitizeIntent } from './mcp-payloads'
+import { sanitizeCapturedValue, sanitizeFreeText } from './mcp-payloads'
 
 type SanitizedRecord = Record<string, unknown>
 
@@ -41,13 +41,13 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
 
   // The intent comes straight from an agent-narrated `context` string, so it can
   // contain a secret the LLM read aloud or personal data it narrated about the
-  // user. `sanitizeIntent` adds structured PII redaction (emails, phone numbers,
+  // user. `sanitizeFreeText` adds structured PII redaction (emails, phone numbers,
   // IPs, cards, SSNs) to the passes every captured value gets, in the one order
   // that works — see its doc comment. PII redaction is scoped to the intent only:
   // structured tool parameters and responses often hold the same shapes as
   // legitimate data.
   if (result.userIntent != null) {
-    result.userIntent = sanitizeIntent(result.userIntent)
+    result.userIntent = sanitizeFreeText(result.userIntent)
   }
 
   if (result.llmModel != null) {

package/src/index.ts

@@ -14,6 +14,7 @@ import { applyMcpLibIdentity } from './extensions/lib-identity'
 import { deriveSessionIdFromMCPSession, getSessionInfo, newSessionId } from './extensions/session'
 import { instrumentLowLevelServer } from './extensions/instrument-lowlevel'
 import { instrumentHighLevelServer } from './extensions/instrument-highlevel'
+import { getFeedbackToolDescriptor, resolveCollectFeedbackOptions } from './extensions/feedback'
 import type {
   CaptureEventData,
   HighLevelMCPServerLike,
@@ -52,6 +53,17 @@ import type {
  */
 function instrument(server: unknown, posthog: PostHog, options: MCPAnalyticsOptions = {}): McpAnalytics {
   const logger = createLogger(options?.logger)
+
+  // Fail fast on a `collectFeedback` config error (reserved extra key,
+  // undeclared extraRequired). Above the graceful-degradation try so it throws
+  // out of instrument() like PostHogMCP's constructor does — inside the catch it
+  // would silently disable ALL analytics for the server, not just feedback.
+  // `options?.` — untyped JavaScript can pass null options (see logger-isolation.test.ts).
+  const feedbackOptions = resolveCollectFeedbackOptions(options?.collectFeedback)
+  if (feedbackOptions) {
+    getFeedbackToolDescriptor(feedbackOptions)
+  }
+
   try {
     if (!posthog) {
       logger('Warning: No PostHog client passed to instrument(). Events will not be sent anywhere.')
@@ -129,6 +141,7 @@ function getLowLevelServer(server: MCPServerLike | HighLevelMCPServerLike): MCPS
  */
 const DEFAULT_OPTIONS = {
   reportMissing: false,
+  collectFeedback: false,
   enableConversationId: false,
 } satisfies Partial<MCPAnalyticsOptions>
 
@@ -215,14 +228,22 @@ export {
 export { getRequestHeaders } from './extensions/request-headers'
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp'
 export { getMoreToolsResult } from './extensions/tools'
+export { sendFeedbackResult, SEND_FEEDBACK_TOOL_NAME } from './extensions/feedback'
 export { setLogger } from './extensions/logger'
 // Re-export the posthog-node client so a single import works:
 //   import { PostHog, instrument } from "@posthog/mcp"
 // posthog-node stays a peer dependency, so this resolves the host app's installed copy.
 export { PostHog, type PostHogOptions } from 'posthog-node'
 export type {
+  FeedbackCaptureData,
+  FeedbackExtraPropertySchema,
+  CollectFeedbackOptions,
+  FeedbackReport,
+  FeedbackSentiment,
+  FeedbackType,
   BeforeSendFn,
   CaptureEventData,
+  CollectFeedbackConfig,
   InitializeCaptureData,
   McpAnalytics,
   McpCaptureCommon,