feat(mcp): PostHog MCP analytics SDK for Python (posthog.mcp)

[lucasheriques]

What

Adds posthog.mcp — a Python SDK for PostHog MCP analytics, the Python sibling of the TypeScript @posthog/mcp package. This is the #1 "what to prioritize next" item on the MCP analytics mega-issue, PostHog/posthog#64016: MCP analytics was TS-only, but many MCP servers are Python.

from posthog import Posthog
from posthog.mcp import instrument
from mcp.server.fastmcp import FastMCP

posthog = Posthog("phc_...", host="https://us.i.posthog.com")
server = FastMCP("my-server")
analytics = instrument(server, posthog)   # one line

Install: pip install posthog[mcp].

How it works

Packaged as a submodule of posthog (mirroring posthog.ai), guarded by an optional mcp extra so import posthog never requires mcp. The wire format is byte-identical to @posthog/mcp's constants.ts, so the existing MCP analytics dashboard ingests Python-server data with zero backend changes.

instrument(server, posthog_client) supports every common Python MCP server:

• FastMCP and the low-level Server from the official modelcontextprotocol/python-sdk (the mcp package)
• jlowin's standalone FastMCP 2.0 (the separate fastmcp package)
• PostHogMCP (a Client subclass) for custom/edge dispatchers with no server object

Captures $mcp_tool_call, $mcp_tools_list, $mcp_initialize (lazy), $identify, $exception, and $mcp_missing_capability. Features: agent-intent capture via an injected context arg, identify, before_send, event_properties, report_missing (get_more_tools), and conversation_id.

Implementation notes:

• FastMCP is instrumented via two central seams (ToolManager.call_tool + the ListToolsRequest handler) rather than per-tool wrapping — late-registered tools are covered automatically.
• jlowin's FastMCP 2.0 routes through the low-level adapter (its _mcp_server subclasses the official Server); it validates against the function signature and rejects unexpected kwargs, so the injected context/conversation_id are stripped before dispatch.
• UUIDv7 implemented inline (no new dependency); $exception_list reuses posthog.exception_utils.
• $mcp_initialize is emitted lazily from client_params because the Python mcp SDK handles initialize in the session layer, not via request_handlers.
• On a raw low-level Server, context/conversation_id are injected as optional schema properties (that schema is also the validation schema) so a call omitting them is never rejected.

Testing

• 56 unit + end-to-end tests (posthog/test/mcp/), driving the real mcp / fastmcp SDK seams with a fake capture client. ruff + mypy clean.
• Dogfooded against project 2: a demo server (examples/mcp_analytics_demo.py) sent the full $mcp_* event set; verified the events ingest with correct intent, error flag, and $mcp_source and are readable by the dashboard.

Links

• 📋 Mega-issue: [mega-issue] MCP Analytics posthog#64016
• 📖 Docs PR: docs(mcp-analytics): add Python SDK install section posthog.com#17827

Status

Alpha (minor changeset). Parity note: the TS instrument() does not emit resources/prompts events, so those are intentionally omitted here too.

---

Created with PostHog Code

[greptile-apps]

_{Reviews (1): Last reviewed commit: "chore(mcp): add changeset for the Python..." | Re-trigger Greptile}

[lucasheriques]

Added support for jlowin's standalone FastMCP 2.0 (the separate fastmcp package), in addition to the official SDK's FastMCP + low-level Server. instrument() now accepts all three (plus PostHogMCP for custom dispatchers).

Implementation: jlowin's FastMCP._mcp_server is a subclass of the official low-level Server, so it routes through the low-level adapter's request_handlers seam. The one wrinkle — FastMCP 2.0 validates tool args against the function signature and rejects unexpected kwargs — is handled by stripping the injected context/conversation_id before dispatch (the low-level adapter is now parameterized: strip + required-advisory for fastmcp 2.0, optional + no-strip for a raw Server). Covered by posthog/test/mcp/test_fastmcp_v2.py (56 tests total; skipped when fastmcp isn't installed).

[github-actions]

posthog-python Compliance Report

Date: 2026-06-26 15:04:42 UTC
Duration: 529939ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	512ms
Format Validation.Event Has Uuid	✅	10007ms
Format Validation.Event Has Lib Properties	✅	10006ms
Format Validation.Distinct Id Is String	✅	10005ms
Format Validation.Token Is Present	✅	10007ms
Format Validation.Custom Properties Preserved	✅	10005ms
Format Validation.Event Has Timestamp	✅	10006ms
Retry Behavior.Retries On 503	✅	18017ms
Retry Behavior.Does Not Retry On 400	✅	12003ms
Retry Behavior.Does Not Retry On 401	✅	10006ms
Retry Behavior.Respects Retry After Header	✅	16012ms
Retry Behavior.Implements Backoff	✅	30017ms
Retry Behavior.Retries On 500	✅	13007ms
Retry Behavior.Retries On 502	✅	16010ms
Retry Behavior.Retries On 504	✅	16009ms
Retry Behavior.Max Retries Respected	✅	30016ms
Deduplication.Generates Unique Uuids	✅	7000ms
Deduplication.Preserves Uuid On Retry	✅	16014ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	23016ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	16005ms
Deduplication.No Duplicate Events In Batch	✅	10000ms
Deduplication.Different Events Have Different Uuids	✅	10007ms
Compression.Sends Gzip When Enabled	✅	10004ms
Batch Format.Uses Proper Batch Structure	✅	10006ms
Batch Format.Flush With No Events Sends Nothing	✅	5004ms
Batch Format.Multiple Events Batched Together	✅	10004ms
Error Handling.Does Not Retry On 403	✅	12007ms
Error Handling.Does Not Retry On 413	✅	10008ms
Error Handling.Retries On 408	✅	14011ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	9501ms
Request Payload.Flags Request Uses V2 Query Param	✅	10005ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	10007ms
Request Payload.Flags Request Omits Authorization Header	✅	10006ms
Request Payload.Token In Flags Body Matches Init	✅	10006ms
Request Payload.Groups Round Trip	✅	10005ms
Request Payload.Groups Default To Empty Object	✅	10006ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	10005ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	10005ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	10006ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	10005ms
Request Lifecycle.No Flags Request On Init Alone	✅	5003ms
Request Lifecycle.No Flags Request On Normal Capture	✅	10506ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	9509ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	10002ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	10508ms

[greptile-apps]

_{Reviews (2): Last reviewed commit: "chore(mcp): regenerate public API snapsh..." | Re-trigger Greptile}

[marandaneto]

just an initial agent review before proper human review:

Blocking / high confidence findings

1. flush() does not wait for sync background captures

   • fire_and_forget() stores concurrent.futures.Future when no event loop is running.
   • drain_pending() only awaits asyncio.Task.
   • This means PostHogMCP/sync custom dispatcher events can still be pending when users call
     flush() then shutdown(), causing dropped trailing events.
   • Files: posthog/mcp/instrumentation.py:59-87.

2. conversation_id can break existing tools

   • Schema injection skips tools that already define conversation_id.
   • But dispatch still strips conversation_id from arguments, treating it as SDK-owned.
   • Also, if a tool owns context, the current strip logic skips stripping both context and
     conversation_id, so an injected conversation_id may be passed into a tool that doesn’t
     accept it.
   • Files: posthog/mcp/conversation_id.py:22-36, posthog/mcp/instrument_fastmcp.py:127-131,
     posthog/mcp/instrument_lowlevel.py:136-142.
   • I’d add tests for tools with real context, real conversation_id, and both.

Medium concerns

3. Fragile dependency range

   • The implementation hooks private/internal MCP SDK seams like _tool_manager, _mcp_server,
     and request_handlers, but dependency is mcp>=1.26.0 with no upper bound.
   • I’d add an upper bound or document/test the supported MCP SDK versions.

4. PostHogMCP requires installing mcp even though it looks usable for custom dispatchers

   • posthog.mcp.init imports/checks mcp before exporting PostHogMCP.
   • If PostHogMCP is meant to support non-official/custom dispatchers, move the import guard
     into instrument()/adapter paths.

[marandaneto]

some comparison with the mcp node based impl.

1. tools/list capture is weaker than TypeScript

TypeScript captures:

• $mcp_response with the returned tools
• $mcp_duration_ms
• $mcp_is_error
• error event if the list handler throws
• special error capture if zero tools are listed

Python currently records mostly:

• $mcp_listed_tool_names
• $mcp_parameters
• $mcp_is_error = False

No response, no duration, no failure capture if original(req) raises.

This is probably the biggest dashboard parity gap.

2. $mcp_initialize is not equivalent

TypeScript wraps the actual initialize handler and captures request, response, and timing.

Python emits initialize lazily from prepare_request(), but prepare_request() only runs on tool
calls. So:

• client that initializes + lists tools but never calls a tool may not emit $mcp_initialize
• Python initialize has no real request params
• no response
• no duration
• identity is not resolved from the initialize request itself

Some limitation may be unavoidable in Python MCP SDK, but Python should at least emit initialize
on first tools/list too, and document remaining differences.

3. Injected arg stripping is inconsistent

TypeScript strips injected context/conversation_id before the tool sees them.

Python FastMCP strips both only when _tool_owns_context(server, name) is false:

  if isinstance(arguments, dict) and not _tool_owns_context(server, name):
      call_arguments = {k: v for k, v in arguments.items() if k not in _INJECTED_KEYS}

That means a tool with a real context arg can also receive injected conversation_id, which is
wrong.

For raw low-level Python, injected args are intentionally left in place. That may be necessary
because the advertised schema is also validation schema, but it is different from JS and should
be explicitly tested/documented.

4. Low-level thrown exceptions are not captured like TS

TypeScript wraps execution with try/catch and captures failed tool events before rethrowing.

Python low-level assumes the MCP handler converts failures into CallToolResult(isError=True). If
a custom/low-level handler raises directly, Python skips $mcp_tool_call/$exception.

Worth wrapping original(req) in try/except anyway.

5. Idempotency/tracking key differs

TypeScript canonicalizes high-level servers to the underlying low-level server before storing
tracking state.

Python stores tracking against whatever object was passed to instrument(). For wrappers exposing
_mcp_server, instrumenting both wrapper and underlying server can create divergent tracking
state while only one wrapped closure is active.

Not common, but TS handles this more robustly.

6. flush() still misses sync background futures

Python added McpAnalytics.flush(), but drain_pending() only awaits asyncio.Task, not the
concurrent.futures.Future created for sync hosts. PostHogMCP sync captures can still be pending.

7. PostHogMCP unnecessarily requires mcp

JS PostHogMCP is useful for custom dispatchers. Python exports PostHogMCP, but importing
posthog.mcp first requires the official mcp package. If custom dispatcher support is real, the
import guard should move into instrument()/adapters.

[lucasheriques]

thanks manoel, this was a really useful pass. fixed all of it across 0d998ab, 37280c2, and f590c8c.

flush() missing sync futures. fixed. drain_pending() waits on the concurrent.futures.Future from the sync path now too, and PostHogMCP.flush()/shutdown() drain before tearing down. without it a trailing event could still be in flight on sync hosts.

conversation_id leaking into context-owning tools. fixed. the two injected keys get stripped independently now, so a tool that declares its own context keeps it while conversation_id still gets stripped. added tests for context-only, conversation_id-only, and both. (the official FastMCP ignores extra kwargs so nothing was crashing, but it was still wrong, and it does bite the stricter fastmcp 2.0 path.)

tools/list weaker than TS. fixed. it captures $mcp_response and $mcp_duration_ms now, and records a failed $mcp_tools_list plus $exception if the list handler raises. agreed this was the biggest gap.

$mcp_initialize not on list-only sessions. fixed. it emits on the first tools/list too, deduped per session. the deeper difference stays: the Python SDK handles initialize in the session layer rather than request_handlers, so there's no real initialize request, response, or timing to capture. left a note in the adapter.

low-level raises not captured. fixed. wrapped original(req) so a handler that raises directly gets captured before re-raising, same as the TS path.

PostHogMCP requiring mcp. fixed. the SDK import and the wrapping adapters are deferred into instrument() now, so from posthog.mcp import PostHogMCP works with nothing extra installed.

idempotency tracking key. fixed. tracking keys on the underlying low-level server now, so instrumenting a high-level FastMCP and its ._mcp_server land on one state instead of two. matches the TS canonicalization.

dependency range. rather than pin via an extra, we now treat the MCP SDK as a peer dependency (you already have it if you built the server) and check the installed version at runtime, warning outside the tested >=1.26,<2 range. dropped the posthog[mcp] extra entirely, so install is just pip install posthog.

still draft until the pypi publish, but ready for a proper read whenever you have time.

[marandaneto]

@lucasheriques still a couple of things left

Key remaining findings:

1. CI is failing

   • Ruff format fails.
   • Local uv run ruff format --check posthog/test/mcp posthog/mcp confirms 5 test files need formatting.
   • MCP tests pass locally: 63 passed, 1 skipped.

2. FastMCP v2 still strips real context / conversation_id args

   • Official FastMCP fix was added, but jlowin FastMCP v2 path still unconditionally pops both injected keys when
     strip_injected=True.
   • This can break tools that legitimately define context or conversation_id.
   • File: posthog/mcp/instrument_lowlevel.py:140-142.

3. tools/list empty-list parity gap remains

   • Node treats zero tools as errored $mcp_tools_list with exception.
   • Python now captures response/duration/errors, but empty lists are still successful.
   • Python: instrument_fastmcp.py:245-289, instrument_lowlevel.py:252-299.
   • Node: packages/mcp/src/extensions/instrumentation.ts:300-308.

4. $mcp_initialize identity attribution still differs (Probably not reasonably fixable through stable Python MCP SDK hooks)

   • Python emits initialize before handle_identify, so first $mcp_initialize is anonymous even when identify resolves
     on the same first list/call.
   • Python: posthog/mcp/instrumentation.py:197-201.
   • Node identifies before building initialize.
   • Node: packages/mcp/src/extensions/instrumentation.ts:427-438.
     can improve attribution, but not true Node parity without deeper/private monkey-patching

5. PostHogMCP cannot disable MCP exception fan-out

   • Python hard-codes enable_exception_autocapture=True.
   • Node respects this.options.enableExceptionAutocapture ?? true.
   • Python: posthog/mcp/posthog_mcp.py:283-286.

6. Runtime MCP version warning likely won’t be visible

   • _warn_if_unsupported_mcp_version() runs before opts.logger is installed, so the warning goes to the default no-op
     logger.
   • Python: posthog/mcp/init.py:193 before set_logger at 201-202.

[lucasheriques]

thanks, all six addressed in d3fbf46.

1. ci / ruff format. my miss, i ran ruff check but not ruff format. formatted the 5 files.
2. v2 stripping real context/conversation_id. fixed, and i switched approach partway. stripping only the keys we injected (tracked from the list) would break stateless per-request servers, where the list ran on a different instance, so nothing gets stripped and jlowin rejects the call. v2 now strips the injected keys except ones the tool declares in its own signature. list-independent and instance-independent. a v2 tool owning context keeps it. added a test.
3. empty tools/list. matched node, zero advertised tools is now an errored $mcp_tools_list with an exception, both adapters.
4. $mcp_initialize identity. identify runs before initialize is emitted now, so the first initialize is attributed instead of anonymous. not byte-parity with node (the python sdk handles initialize in the session layer, not request_handlers, so there's no real request/response/timing) but the attribution gap is closed.
5. PostHogMCP exception fan-out. added mcp_exception_autocapture (default true) so it can be turned off like node. kept distinct from the inherited Client.enable_exception_autocapture, which is the global uncaught-error hook and means something different.
6. version warning visibility. my bug, fixed. the logger is installed before the version check now, so the advisory actually shows.

71 tests pass, ruff + mypy clean. ci should be green now.

[marandaneto]

nice, left a last comment here otherwise LGTM
approving to unblock