[gesh]

Problem

• MCP clients list tools on every reconnect, so $mcp_tools_list is about as common as $mcp_tool_call.
• On PostHog's own MCP server, it was 30% of all MCP events in the last 7 days: 17.4M events, against 17.2M tool calls.
• Hosts that do not use the event pay for it and cannot turn it off.

Follows #5401, which added the same option for $mcp_initialize. Part of one change across three repos: PostHog/posthog-python#1116 and PostHog/sdk-specs#142.

Changes

• New option sendToolsListEvent. DEFAULT_OPTIONS sets it to true, so nothing changes unless a host turns it off.
• The name says "event", like sendInitializeEvent in feat(mcp): add a sendInitializeEvent option #5401. PostHogMCP.captureToolsList() already captures the event by hand.
• Three places send the event: a listing, an empty listing, and a failed one. Each one checks sendToolsListEvent with a plain if, as feat(mcp): add a sendInitializeEvent option #5401 does for $mcp_initialize. A failed listing's $exception goes too.
• Nothing else changes. Tools keep their injected arguments, and the virtual tools stay listed.
• README line and a brief minor changeset.

Testing

• send-tools-list-event.test.ts runs a real McpServer and client with the option on and off. A listing sends one or no $mcp_tools_list. The listed schema still has the injected context, and the tool call still records its intent.
• A second test checks that a failed listing sends no event and no $exception.
• Without the checks, the two option-off tests fail.
• The unit suite passes (990 tests), and so do types, lint and format.
• test:integration:sdk-v1 and test:integration:sdk-v2 pass. That includes the v2 matrix with its longlived rows.

Release info Sub-libraries affected

Libraries affected

• @posthog/mcp (minor: new option, off changes one event)

Checklist

• All commits are signed
• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code, model Claude Opus 5.5 (claude-opus-5-5).
• The option only stops the event. The tools/list wrapper still injects arguments, because tool calls depend on them.

🤖 Generated with Claude Code

[github-actions]

Coherence

0 spec problems · 0 failing chokepoints · 2 spec gaps · 0 guard failures

44 components, 7 bullets (5 invariants, 2 requirements), 0 problems

Chokepoints: none declared.

Spec gaps: 2 entrances with outside or unknown trust and no traced control, and 10 more held by the adoption baseline

• packages/web/Web.spec.md entrance public api (trust host-app): packages/web
• packages/webpack-plugin/Webpack-plugin.spec.md entrance webpack plugin (trust build): packages/webpack-plugin

Close one with guard: <chokepoint>, an invariant that names it on its entrances: line, or control: none — <reason>; scaffold control proposes it.

[gesh]

@PostHog review

[posthog]

@gesh PostHog Review is reviewing this pull request.

[posthog]

PostHog Review · Standard · reviewed 3cbc53a: no findings.

[stamphog]

Not approved — escalated to a human reviewer.

Re-add the stamphog label to request another review once you have addressed this.

The disclosed changes enter public API and analytics write-path territory without current-head independent assurance; the older review does not cover the current head. Request a current-head review from Manoel Aranda Neto, another teammate, or an agent reviewer before re-requesting.

• Author wrote 0% of the modified lines and has 31 merged PRs in these paths (familiarity MODERATE).
• Risky territory without independent assurance: Public API contracts — packages/mcp/src/types.ts adds an optional setting to the exported MCPAnalyticsOptions interface, with its default supplied in packages/mcp/src/index.ts.; Data ingestion or write paths — packages/mcp/src/extensions/instrumentation.ts conditionally suppresses analytics capture for successful, empty, and failed tool listings, including associated exception events.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	21L, 3F substantive, 89L/6F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (89L, 6F, two-areas, feat)
stamphog 2.6.1		.stamphog/policy.yml @ cca259f · reviewed head cca259f

[lucasheriques]

LGTM, approving. One nit inline; the naming question on #5401 applies here too.

[lucasheriques]

nit: could this be the same shape as captureInitialize in #5401, a plain if (data.options.captureToolsList !== false) at the emit points? The ...args: Parameters<typeof captureEvent> wrapper that looks up the tracking data again through args[0] is a bit indirect, and having the two options gated two different ways in the same file will trip someone up. getTracedToolsList would need data (or the flag) passed in, which seems fine.

[gesh]

Agreed, fixed in 56ad84b: each emit point now checks sendToolsListEvent with a plain if, like sendInitializeEvent. The option is also renamed to sendToolsListEvent (dfd1f28), to match #5401.