@posthog/mcp 0.14.0 → 0.15.0

package/src/extensions/instrument-lowlevel.ts

@@ -11,6 +11,7 @@ import { handleReportMissing, resolveMissingCapabilityToolName } from './tools'
 import {
   handleInitializeRequest,
   handleListToolsRequest,
+  traceResourceRequest,
   patchRequestHandlers,
   registerFallbackRequestHandler,
   captureToolCall,
@@ -27,9 +28,10 @@ type MCPRequest = Parameters<MCPRequestHandler>[0]
 type MCPRequestExtra = Parameters<MCPRequestHandler>[1]
 
 /**
- * Instruments a low-level `Server`: wraps `initialize`, `tools/list`, and
- * `tools/call`. The tool-call lifecycle is delegated to {@link captureToolCall},
- * shared with the high-level wrapper.
+ * Instruments a low-level `Server`: wraps `initialize`, `tools/list`,
+ * `tools/call`, `resources/list`, `resources/templates/list`, and
+ * `resources/read`. The tool-call lifecycle is delegated to
+ * {@link captureToolCall}, shared with the high-level wrapper.
  */
 export function instrumentLowLevelServer(server: MCPServerLike, logger: LoggerFn): void {
   try {
@@ -42,6 +44,11 @@ export function instrumentLowLevelServer(server: MCPServerLike, logger: LoggerFn
       'tools/list': (server, originalHandler, request, extra) =>
         handleListToolsRequest(server, originalHandler, request, extra, logger),
       'tools/call': traceToolCall,
+      '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.
+      'resources/templates/list': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesList, logger),
+      'resources/read': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesRead, logger),
     }
     patchRequestHandlers(server, handlers)
 

package/src/extensions/instrumentation.ts

@@ -395,6 +395,111 @@ function publishFailedToolEvent(
   }
 }
 
+type ResourceEventType = typeof MCPAnalyticsEventType.mcpResourcesList | typeof MCPAnalyticsEventType.mcpResourcesRead
+
+interface TraceRequestParams {
+  server: MCPServerLike
+  originalHandler: MCPRequestHandler
+  request: MCPRequestLike
+  extra: CompatibleRequestHandlerExtra | undefined
+  eventType: ResourceEventType
+  logger: LoggerFn
+}
+
+/** One resource request's outcome: either the handler threw, or it returned. */
+type ResourceOutcome = { error: unknown } | { result: unknown }
+
+/**
+ * Stamps a resource request's outcome onto its prepared event and publishes it.
+ *
+ * A listing's result is captured as the event response; a read's is not. What
+ * `resources/list` and `resources/templates/list` return is discovery metadata —
+ * names, uris, mime types, the next cursor — which answers "what did this client
+ * actually see?", while a read returns the resource body itself, which analytics
+ * has no business holding.
+ */
+function publishResourceEvent(
+  server: MCPServerLike,
+  preparedEvent: PreparedToolEvent | null,
+  startTime: Date,
+  params: TraceRequestParams,
+  outcome: ResourceOutcome
+): void {
+  if (!preparedEvent) {
+    return
+  }
+  const { event, requestAttribution } = preparedEvent
+  // Stamping is inside the `try` with the publish: `captureException` reads the
+  // thrown value's own `stack`, which an application error is free to define as
+  // a throwing getter. Outside, that would replace the resource error the caller
+  // is waiting on with ours.
+  try {
+    if ('error' in outcome) {
+      event.isError = true
+      event.error = captureException(outcome.error)
+    } else {
+      event.isError = false
+      if (params.eventType === MCPAnalyticsEventType.mcpResourcesList) {
+        event.response = outcome.result
+      }
+    }
+    event.duration = Date.now() - startTime.getTime()
+    captureEvent(server, event, params.logger, requestAttribution)
+  } catch (error) {
+    params.logger(`Warning: PostHog MCP analytics failed to publish ${params.request.method} analytics - ${error}`)
+  }
+}
+
+/** Builds the handler patch that captures one resource method, for either adapter. */
+export function traceResourceRequest(eventType: ResourceEventType, logger: LoggerFn): HandlerPatch {
+  return (server, originalHandler, request, extra) =>
+    captureResourceRequest({ server, originalHandler, request, extra, eventType, logger })
+}
+
+/** Captures a non-tool MCP request without changing its result or error semantics. */
+async function captureResourceRequest(params: TraceRequestParams): Promise<unknown> {
+  const { server, originalHandler, request, extra, eventType, logger } = params
+  const data = getServerTrackingData(server)
+  if (!data) {
+    logger(
+      'Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using resources.'
+    )
+    return await originalHandler(request, extra)
+  }
+
+  const startTime = new Date()
+  let preparedEvent: PreparedToolEvent | null = null
+  try {
+    const sessionId = getSessionId(server, extra)
+    const sessionInfo = getSessionInfo(server, data, sessionId)
+    const event: McpEvent = {
+      sessionId,
+      eventType,
+      parameters: buildCapturedMcpParameters(request),
+      resourceName: eventType === MCPAnalyticsEventType.mcpResourcesRead ? request.params?.uri : undefined,
+      timestamp: startTime,
+    }
+    stampClientIdentity(event, request, extra, server)
+    stampTransportIdentity(event, extra)
+    const identity = await handleIdentify(server, data, sessionId, request, sessionInfo, extra)
+    await applyResolvedMetadata(event, data, request, extra)
+    preparedEvent = { event, requestAttribution: withIdentity(sessionInfo, identity) }
+  } catch (error) {
+    logger(`Warning: PostHog MCP analytics could not prepare ${request.method} analytics - ${error}`)
+  }
+
+  let result: unknown
+  try {
+    result = await originalHandler(request, extra)
+  } catch (error) {
+    publishResourceEvent(server, preparedEvent, startTime, params, { error })
+    throw error
+  }
+
+  publishResourceEvent(server, preparedEvent, startTime, params, { result })
+  return result
+}
+
 // --- tools/list -----------------------------------------------------------
 
 /**

package/src/extensions/internal.ts

@@ -226,15 +226,26 @@ export async function resolveEventProperties(
   }
 }
 
+/**
+ * Names what a request is about, for `$identify`. `resources/read` addresses its
+ * subject by `uri` rather than `name`, so an identify published from a read used
+ * to report `Unknown`.
+ */
 function getRequestResourceName(request: unknown): string {
   if (!request || typeof request !== 'object' || !('params' in request)) {
     return 'Unknown'
   }
 
   const params = request.params
-  if (!params || typeof params !== 'object' || !('name' in params)) {
+  if (!params || typeof params !== 'object') {
     return 'Unknown'
   }
 
-  return typeof params.name === 'string' ? params.name : 'Unknown'
+  for (const key of ['name', 'uri'] as const) {
+    const value = (params as Record<string, unknown>)[key]
+    if (typeof value === 'string') {
+      return value
+    }
+  }
+  return 'Unknown'
 }

package/src/extensions/mcp-payloads.ts

@@ -16,6 +16,55 @@ const POSTHOG_TOKEN_PATTERN = /\bph[a-z]_[A-Za-z0-9_-]{20,}\b/g
 const SENSITIVE_KEY_PATTERN =
   /^(authorization|cookie|set-cookie|x-api-key|api[-_]?key|api[-_]?token|access[-_]?token|refresh[-_]?token|token|password|secret|client[-_]?secret|private[-_]?key)$/i
 
+// Deliberately no leading `\b`: `_` is a word character but not scheme-legal, so
+// `resource_https://user:pw@host` has no boundary to anchor to and would keep its
+// credentials. Leftmost matching makes `foo.https://x` match from `f` with scheme
+// `foo.https`, which redacts the same URL and is therefore harmless.
+//
+// `'` is a valid URI sub-delimiter, so the terminal class must not stop at one:
+// excluding it truncated `https://example.com/o'reilly?token=x` at the path and
+// shipped the token in the clear. Only the characters that are never valid
+// unencoded in a URI are excluded.
+//
+// The authority is optional too. An MCP resource URI frequently has none
+// (`resource:guide?token=x`, `file:/guide.md`), and requiring `//` let those
+// through untouched; `[^\s<>"]+` absorbs a `//host` when there is one. The cost
+// is over-matching ordinary prose (`Error:foo`, `at12:30`, `C:\path`), which is
+// harmless: a match with nothing to redact is returned byte-for-byte, so the
+// text around it is never rewritten.
+const URL_PATTERN = /[a-z][a-z0-9+.-]{0,63}:[^\s<>"]+/gi
+/** The same pattern without `g`, for asking whether a value holds a URL at all. */
+const URL_PATTERN_ONCE = new RegExp(URL_PATTERN.source, 'i')
+/** Finds the first scheme that brings a real authority, i.e. what the pattern required before it went authority-less. */
+const URL_AUTHORITY_SEARCH = /[a-z][a-z0-9+.-]{0,63}:\/\//i
+/** The same, anchored: does this match *open* with an authority? */
+const URL_AUTHORITY_PATTERN = new RegExp(`^${URL_AUTHORITY_SEARCH.source}`, 'i')
+/** Every authority start in a value, in order. */
+const URL_AUTHORITY_SEARCH_ALL = new RegExp(URL_AUTHORITY_SEARCH.source, 'gi')
+/** The field separators. `?` and `#` are structural only as delimiters — see {@link isStructural}. */
+const URL_FIELD_CHARACTERS = '=&'
+/** The legacy field separator. Never split on, only checked; see {@link sanitizeUrlFieldValue}. */
+const LEGACY_FIELD_SEPARATOR = ';'
+// The terminal class above also absorbs the prose punctuation that follows a URL
+// in a sentence, `'` included now that a URL can contain one. See
+// `splitTrailingPunctuation`.
+const URL_TRAILING_PUNCTUATION = ".,;:!?)]}'"
+const MAX_URL_LENGTH = 8192
+const MAX_URL_QUERY_FIELDS = 128
+// A query key is sensitive when any `-`/`_`/`.`/`/`/`;`-delimited segment names
+// a credential, so compound names (`private_token`, `oauth_signature`,
+// `subscription-key`, `X-Amz-Security-Token`, `Key-Pair-Id`) are covered without
+// enumerating every vendor's spelling. `/` is a separator because a fragment's
+// field list can be written `#/token=…`, and `;` because a legacy `;`-separated
+// pair parses into a single key (`download;token`) — either would otherwise hide
+// the name. Over-redacting a benign `sort_key` — or `sort/key`, or `sort;key` —
+// is the accepted trade for an analytics payload.
+const SENSITIVE_QUERY_KEY_SEGMENT_PATTERN =
+  /(^|[-_./;])(auth|token|secret|password|passwd|pwd|credential|signature|sig|key|hmac|sas|bearer|jwt|session|sessionid)([-_./;]|$)/i
+// `code` — the OAuth authorization code — is matched only as a whole key: as a
+// segment it would eat `country_code`, `zip_code`, and `lang_code`.
+const SENSITIVE_QUERY_KEY_EXACT_PATTERN = /^(code|AWSAccessKeyId|GoogleAccessId|Policy)$/i
+
 // PII redaction for the agent-narrated intent string only. `$mcp_intent` is free
 // text the calling LLM writes into the injected `context` argument, so it can
 // carry personal data the model read aloud despite being told not to. We redact
@@ -75,6 +124,12 @@ function shouldRedactKey(key: string): boolean {
   return SENSITIVE_KEY_PATTERN.test(key)
 }
 
+function shouldRedactQueryKey(key: string): boolean {
+  return (
+    shouldRedactKey(key) || SENSITIVE_QUERY_KEY_SEGMENT_PATTERN.test(key) || SENSITIVE_QUERY_KEY_EXACT_PATTERN.test(key)
+  )
+}
+
 function isBase64DataUrl(value: string): boolean {
   const prefix = BASE64_DATA_URL_PREFIX_PATTERN.exec(value)
   if (!prefix) {
@@ -91,16 +146,384 @@ function isBase64DataUrl(value: string): boolean {
   return BASE64_DATA_URL_PAYLOAD_PATTERN.test(payload.replace(/[\r\n]/g, ''))
 }
 
-function sanitizeString(value: string): string {
-  if (
+function exceedsUrlFieldLimit(fields: string): boolean {
+  return fields.split('&', MAX_URL_QUERY_FIELDS + 1).length > MAX_URL_QUERY_FIELDS
+}
+
+/** How much of the sanitizer one call is allowed to apply. */
+interface UrlSanitizeMode {
+  /** Sanitize a URL found inside a retained field value. Off past depth 1. */
+  allowNestedUrls: boolean
+  /** Split prose punctuation off the end. Off when the match is a whole string. */
+  stripPunctuation: boolean
+}
+
+/** Whether any `;`-separated piece of `value` names a credential. */
+function hasLegacySensitiveField(value: string): boolean {
+  return value.split(LEGACY_FIELD_SEPARATOR).some((piece) => shouldRedactQueryKey(piece.split('=', 1)[0]))
+}
+
+/** The sanitized value of one query or fragment field. */
+function sanitizeUrlFieldValue(key: string, value: string, allowNestedUrls: boolean): string {
+  if (shouldRedactQueryKey(key)) {
+    return REDACTED_VALUE
+  }
+  // `;` once separated fields the way `&` does, so a value carrying one may hold
+  // a credential field inside it. Splitting on it is not an option — that cuts a
+  // credential's own value in two and publishes the tail as a bare key
+  // (`?password=prefix;rest`) — so instead the whole value goes when any piece
+  // of it names a credential.
+  if (value.includes(LEGACY_FIELD_SEPARATOR) && hasLegacySensitiveField(value)) {
+    return REDACTED_VALUE
+  }
+  if (!URL_PATTERN_ONCE.test(value)) {
+    return value
+  }
+  // One level of nesting is the whole budget. Past it a URL-bearing value is
+  // dropped rather than trusted: nothing deeper would sanitize it, so a gateway
+  // address wrapping a gateway address would otherwise ship its credentials.
+  return allowNestedUrls
+    ? sanitizeUrlsInString(value, { allowNestedUrls: false, stripPunctuation: true })
+    : REDACTED_VALUE
+}
+
+/**
+ * Redacts the values of credential-named fields in one `&`-separated field list
+ * — a query string or a fragment. `serialized` is only meaningful when `changed`
+ * is true, so an untouched part keeps its original encoding instead of being
+ * re-serialized. `lastFieldSensitive` says whether whatever follows the list
+ * could be more of a credential, which is what decides both the fragment tail
+ * and restored prose punctuation; see {@link sanitizeUrl}.
+ */
+function sanitizeUrlFields(
+  fields: string,
+  allowNestedUrls: boolean
+): { changed: boolean; lastFieldSensitive: boolean; serialized: string } {
+  const sanitized = new URLSearchParams()
+  let changed = false
+  let lastFieldSensitive = false
+  for (const [key, value] of new URLSearchParams(fields)) {
+    const sanitizedValue = sanitizeUrlFieldValue(key, value, allowNestedUrls)
+    // `changed` is compared, not inferred from the key: the PostHog-token pass
+    // runs first, so a value can already read `[redacted]`, and calling that a
+    // change would re-serialize the field only to percent-encode it.
+    changed ||= sanitizedValue !== value
+    // Sensitivity is the separate question — whether what follows this field
+    // could be more of a credential — and an already-redacted value is still a
+    // credential's field.
+    lastFieldSensitive = shouldRedactQueryKey(key) || sanitizedValue !== value
+    sanitized.append(key, sanitizedValue)
+  }
+  return { changed, lastFieldSensitive, serialized: sanitized.toString() }
+}
+
+/**
+ * Splits the prose punctuation that follows a URL in a sentence off the end of a
+ * match, so it is not parsed as part of the address and can be re-appended
+ * verbatim to whatever the sanitizer returns.
+ *
+ * Walked back character by character rather than matched with a `$`-anchored
+ * pattern: a captured URI is attacker-influenceable, and on a long punctuation
+ * run that does not end the match a backtracking pattern is quadratic.
+ */
+function splitTrailingPunctuation(value: string): { address: string; suffix: string } {
+  let end = value.length
+  while (end > 0 && URL_TRAILING_PUNCTUATION.includes(value[end - 1])) {
+    end--
+  }
+  return { address: value.slice(0, end), suffix: value.slice(end) }
+}
+
+/**
+ * A fragment's tail, given how its head came out.
+ *
+ * A `?` inside a credential looks exactly like the one between a route and its
+ * fields. So when the head's last field is a credential's, everything after that
+ * `?` may be the rest of its value — `#password=prefix?rest` — and the
+ * tail goes whole rather than being read on its own terms. An empty tail has
+ * nothing to hide and stays empty. Either way it counts as a rewritten trailing
+ * field, so prose punctuation after the URL goes with it for the same reason.
+ */
+function sanitizeFragmentTail(
+  tail: string,
+  headLastFieldSensitive: boolean,
+  allowNestedUrls: boolean
+): { value: string; lastFieldSensitive: boolean } {
+  if (!headLastFieldSensitive) {
+    return sanitizeFragmentPart(tail, allowNestedUrls)
+  }
+  return { value: tail === '' ? '' : REDACTED_VALUE, lastFieldSensitive: true }
+}
+
+/**
+ * Splits a fragment at its first `?`. `tail` is null when there is none.
+ *
+ * Nothing is assumed about either part. Shape alone cannot tell a router's route
+ * from a field list — `#/docs/id=1?token=…` puts an `=` in the route, and
+ * `#/token=…&next=https://x/?page=1` puts a `/` and a `?` in a field list — so
+ * each part is read as fields when it holds an `=` and as text otherwise.
+ */
+function splitFragmentParts(hash: string): { head: string; tail: string | null } {
+  const fragment = hash.slice(1)
+  const separator = fragment.indexOf('?')
+  if (separator < 0) {
+    return { head: fragment, tail: null }
+  }
+  return { head: fragment.slice(0, separator), tail: fragment.slice(separator + 1) }
+}
+
+/** One fragment part, and whether its last field was rewritten. */
+function sanitizeFragmentPart(part: string, allowNestedUrls: boolean): { value: string; lastFieldSensitive: boolean } {
+  if (!part.includes('=')) {
+    return { value: sanitizeFragmentText(part, allowNestedUrls), lastFieldSensitive: false }
+  }
+  const fields = sanitizeUrlFields(part, allowNestedUrls)
+  // Verbatim unless something was actually rewritten: only the part that changed
+  // should change encoding.
+  return { value: fields.changed ? fields.serialized : part, lastFieldSensitive: fields.lastFieldSensitive }
+}
+
+/**
+ * Sanitizes the part of a fragment that is text rather than fields — a plain
+ * `#intro`, or the route in front of a field list. It is text, and text can
+ * carry an address, so it gets the URL pass.
+ *
+ * Depth is capped the way a field value's is: at the nested level a URL-bearing
+ * text is dropped rather than descended into. That is also what stops
+ * `resource:x#resource:x#…` from recursing once per `#`.
+ */
+function sanitizeFragmentText(text: string, allowNestedUrls: boolean): string {
+  if (!allowNestedUrls) {
+    return URL_PATTERN_ONCE.test(text) ? REDACTED_VALUE : text
+  }
+  return sanitizeUrlsInString(text, { allowNestedUrls: false, stripPunctuation: true })
+}
+
+/**
+ * Every offset inside `value` where an adjacent address starts; see
+ * {@link sanitizeUrl}.
+ *
+ * An authority is in *value position* — left alone, because the field pass
+ * already gives it the nested pass — when a field name's `=` is the nearest
+ * structural character behind it. Structural means a field separator (`=`, `&`,
+ * `;`) or one of the URL's three delimiters; see {@link isDelimiter}. Before any
+ * delimiter no `=` has been seen, so `…/redirect=https://user:pw@host` is two
+ * addresses rather than one field.
+ *
+ * Decided in one forward walk, not a backward scan per authority. The scan was
+ * quadratic on a value that opens its fields once and then runs thousands of
+ * addresses together, because every one of them scanned back to the same `?`.
+ */
+function findEmbeddedAuthorityIndexes(value: string): number[] {
+  const starts = [...value.matchAll(URL_AUTHORITY_SEARCH_ALL)].map((match) => match.index)
+  const indexes: number[] = []
+  const delimiters = { query: false, fragment: false, fragmentQuery: false }
+  let pending = 0
+  let inFields = false
+  let lastStructural = ''
+  for (let cursor = 0; cursor < value.length && pending < starts.length; cursor++) {
+    if (starts[pending] === cursor) {
+      if (cursor > 0 && lastStructural !== '=') {
+        indexes.push(cursor)
+      }
+      pending++
+    }
+    const character = value[cursor]
+    if (isDelimiter(character, delimiters, lastStructural)) {
+      lastStructural = character
+      inFields = true
+    } else if (inFields && URL_FIELD_CHARACTERS.includes(character)) {
+      lastStructural = character
+    }
+  }
+  return indexes
+}
+
+/**
+ * Whether this `?` or `#` is one of a URL's three delimiters, consuming it if so.
+ *
+ * A URL has exactly one query delimiter, one fragment delimiter, and — matching
+ * how the fragment is split — one delimiter between the fragment's own head and
+ * tail. Every other `?` or `#` is ordinary text inside a value, and reading one
+ * as structural would cut `?token=prefix?https://secret/…` in half at a `?` that
+ * belongs to the token.
+ */
+function isDelimiter(
+  character: string,
+  seen: { query: boolean; fragment: boolean; fragmentQuery: boolean },
+  lastStructural: string
+): boolean {
+  if (character === '#') {
+    return seen.fragment ? false : (seen.fragment = true)
+  }
+  if (character !== '?') {
+    return false
+  }
+  if (seen.fragment) {
+    // Inside a fragment, a `?` right after a field name may belong to that
+    // field's value rather than open the tail. Leaving it unstructural keeps a
+    // following address attached, so the fragment split and its fail-closed tail
+    // rule get to decide — they can see the whole credential, this cannot.
+    if (lastStructural === '=') {
+      return false
+    }
+    return seen.fragmentQuery ? false : (seen.fragmentQuery = true)
+  }
+  return seen.query ? false : (seen.query = true)
+}
+
+/**
+ * Redacts the credentials embedded in one URL-shaped match: the userinfo, plus
+ * the values of credential-named query and fragment fields. A retained value that
+ * is itself a URL — a gateway's `?url=` passthrough — gets the same pass one
+ * level deep.
+ *
+ * One match can hold more than one address: a prose word in front of it
+ * (`Failed URL:https://…`, `a:b:https://…`), several run together
+ * (`…/doc,https://…`), or one parked in another's query or fragment
+ * (`…/?download)[b](https://…`). The later address always begins inside what
+ * would parse as the earlier one's path, query key, or fragment — none of which
+ * is examined for userinfo — so it is cut out and sanitized on its own.
+ *
+ * The exception is an authority in value position (see
+ * {@link findEmbeddedAuthorityIndexes}), which the field pass already gives the
+ * nested pass. Cutting there would take a gateway's `?url=https://…` out of the
+ * field it belongs to.
+ *
+ * One pass, no recursion: after the cuts, every authority left inside a piece is
+ * either at its start or in value position, so no piece can need cutting again.
+ *
+ * Every piece but the last is sanitized without the punctuation split: it is
+ * followed by an address rather than by prose, so its last character is a
+ * separator, not a sentence's. (It matters — stripping the `:` off `URL:` would
+ * leave `URL`, which `new URL()` rejects, and the prose word would become
+ * `[redacted]`.)
+ */
+function sanitizeUrl(value: string, mode: UrlSanitizeMode): string {
+  const embedded = findEmbeddedAuthorityIndexes(value)
+  if (embedded.length === 0) {
+    return sanitizeSingleUrl(value, mode)
+  }
+  let result = ''
+  let start = 0
+  for (const index of embedded) {
+    result += sanitizeSingleUrl(value.slice(start, index), { ...mode, stripPunctuation: false })
+    start = index
+  }
+  return result + sanitizeSingleUrl(value.slice(start), mode)
+}
+
+/** {@link sanitizeUrl} for a value already known to hold exactly one address. */
+function sanitizeSingleUrl(value: string, mode: UrlSanitizeMode): string {
+  // The length bound caps the work an attacker-shaped address can force, so it
+  // only applies to a match that has an authority. A long authority-less match
+  // is usually a data URI; it is parsed like any other, which is linear in
+  // `new URL()` and still capped by the field bound below, and comes back
+  // byte-for-byte when it holds nothing to redact.
+  if (value.length > MAX_URL_LENGTH && URL_AUTHORITY_PATTERN.test(value)) {
+    return REDACTED_VALUE
+  }
+
+  const { address, suffix } = mode.stripPunctuation ? splitTrailingPunctuation(value) : { address: value, suffix: '' }
+  let url: URL
+  try {
+    url = new URL(address)
+  } catch {
+    return REDACTED_VALUE + suffix
+  }
+
+  const query = url.search.slice(1)
+  const hasFragment = url.hash !== ''
+  const fragment = splitFragmentParts(url.hash)
+  if (exceedsUrlFieldLimit(query) || exceedsUrlFieldLimit(fragment.head) || exceedsUrlFieldLimit(fragment.tail ?? '')) {
+    return REDACTED_VALUE + suffix
+  }
+
+  let changed = false
+  if (url.username || url.password) {
+    url.username = REDACTED_VALUE
+    url.password = ''
+    changed = true
+  }
+  const sanitizedQuery = sanitizeUrlFields(query, mode.allowNestedUrls)
+  if (sanitizedQuery.changed) {
+    url.search = sanitizedQuery.serialized
+    changed = true
+  }
+  const sanitizedHead = sanitizeFragmentPart(fragment.head, mode.allowNestedUrls)
+  const sanitizedTail =
+    fragment.tail === null
+      ? null
+      : sanitizeFragmentTail(fragment.tail, sanitizedHead.lastFieldSensitive, mode.allowNestedUrls)
+  const sanitizedHash = sanitizedTail === null ? sanitizedHead.value : `${sanitizedHead.value}?${sanitizedTail.value}`
+  if (sanitizedHash !== url.hash.slice(1)) {
+    url.hash = sanitizedHash
+    changed = true
+  }
+
+  // The punctuation split off the end may be the tail of the very credential
+  // just replaced (`?password=fakepass!!!`) rather than the sentence's. When the
+  // last field of the URL's trailing part is a credential's the punctuation goes
+  // with it; losing a comma from the surrounding prose is the accepted cost of
+  // not shipping `!!!`.
+  const trailingFields = hasFragment ? (sanitizedTail ?? sanitizedHead) : sanitizedQuery
+  return (changed ? url.toString() : address) + (trailingFields.lastFieldSensitive ? '' : suffix)
+}
+
+/**
+ * Replaces every URL-shaped match in `text`.
+ *
+ * A match that IS the whole string is an address rather than prose — a captured
+ * `$mcp_resource_name`, a `params.uri`, a nested `?url=` value — so nothing is
+ * split off its end: a trailing `!` there belongs to the URL.
+ */
+function sanitizeUrlsInString(text: string, mode: UrlSanitizeMode): string {
+  return text.replace(URL_PATTERN, (match) =>
+    sanitizeUrl(match, { ...mode, stripPunctuation: mode.stripPunctuation && match.length !== text.length })
+  )
+}
+
+/** Whether a string is large enough, and shaped enough like base64, to be a blob. */
+function isBinaryBlob(value: string): boolean {
+  return (
     value.length >= SIZE_GATE &&
     (BASE64_PATTERN.test(value) ||
       isBase64DataUrl(value) ||
       (BASE64URL_SPECIFIC_CHAR_PATTERN.test(value) && BASE64URL_PATTERN.test(value)))
-  ) {
+  )
+}
+
+/** Replaces PostHog API keys wherever they appear in a string. */
+function redactCredentials(value: string): string {
+  return value.replace(POSTHOG_TOKEN_PATTERN, REDACTED_VALUE)
+}
+
+/** Replaces every URL-shaped match, credentials and all. */
+function redactUrls(value: string): string {
+  return sanitizeUrlsInString(value, { allowNestedUrls: true, stripPunctuation: true })
+}
+
+function sanitizeString(value: string): string {
+  return isBinaryBlob(value) ? BINARY_REDACTED_VALUE : redactUrls(redactCredentials(value))
+}
+
+/**
+ * Sanitizes the agent-narrated intent: 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
+ * base64 is enough — stops it looking like base64 and would ship it whole.
+ * Credentials go before PII, because a PII pattern can cut a token in half (a
+ * phone-shaped run inside one) and leave the halves behind. PII goes before the
+ * URL pass, because the URL rewrite percent-encodes the `@` that the email
+ * pattern anchors on.
+ */
+export function sanitizeIntent(value: string): string {
+  if (isBinaryBlob(value)) {
     return BINARY_REDACTED_VALUE
   }
-  return value.replace(POSTHOG_TOKEN_PATTERN, REDACTED_VALUE)
+  return redactUrls(redactPii(redactCredentials(value)))
 }
 
 function passesLuhn(digits: string): boolean {

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 { redactPii, sanitizeCapturedValue } from './mcp-payloads'
+import { sanitizeCapturedValue, sanitizeIntent } from './mcp-payloads'
 
 type SanitizedRecord = Record<string, unknown>
 
@@ -32,14 +32,22 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
     result.parameters = sanitizeParameters(result.parameters)
   }
 
+  // Every event type, not just `resources/read`: `$identify` and the `$exception`
+  // sibling carry the same name, and a tool or prompt name is free text an
+  // application can spell as a URL too.
+  if (result.resourceName != null) {
+    result.resourceName = sanitizeCapturedValue(result.resourceName) as string
+  }
+
   // 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. Redact it like any other captured value, then strip structured PII
-  // (emails, phone numbers, IPs, cards, SSNs) rather than shipping it raw as
-  // `$mcp_intent`. PII redaction is scoped to the intent only — structured tool
-  // parameters and responses often hold the same shapes as legitimate data.
+  // user. `sanitizeIntent` 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 = redactPii(sanitizeCapturedValue(result.userIntent) as string)
+    result.userIntent = sanitizeIntent(result.userIntent)
   }
 
   if (result.llmModel != null) {