From 6a29b3cf21921920310fdac176a55d17f5ad9d71 Mon Sep 17 00:00:00 2001 From: Lucas Faria Date: Fri, 6 Nov 2026 14:13:00 -0300 Subject: [PATCH] feat(mcp): declare posthog.mcp stable What: a Versioning section in the posthog.mcp README and a release note saying the API and the $mcp_* event schema are stable from this release. Why: posthog.mcp now counts calls the same way as the spec and the other SDKs (posthog-python#1199), so it can make the stability promise sdk-specs#189 defines. It ships inside posthog 7.x, so there's no separate version bump. Tested: docs and release note only; no code change. --- .sampo/changesets/mcp-python-stable.md | 5 +++++ posthog/mcp/README.md | 4 ++++ 2 files changed, 9 insertions(+) create mode 100644 .sampo/changesets/mcp-python-stable.md diff --git a/.sampo/changesets/mcp-python-stable.md b/.sampo/changesets/mcp-python-stable.md new file mode 100644 index 000000000..8283c3305 --- /dev/null +++ b/.sampo/changesets/mcp-python-stable.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +`posthog.mcp` is now stable. From this release, a minor or patch release of `posthog` no longer makes breaking changes to the `posthog.mcp` API, renames or removes a `$mcp_*` event or property, changes its type, or changes which requests send an event, so your saved insights keep working across upgrades. New events and properties can still arrive in minor releases. Upgrading needs no code change. diff --git a/posthog/mcp/README.md b/posthog/mcp/README.md index 464036161..d2a0f57fc 100644 --- a/posthog/mcp/README.md +++ b/posthog/mcp/README.md @@ -36,6 +36,10 @@ Request headers use the same identity and package version, so SDK Health can com Because `$lib` is a client-level identity, `instrument()` relabels every event sent by the client passed to it. Use a client dedicated to MCP analytics if the application also captures unrelated events. +## Versioning + +`posthog.mcp` is stable. It ships inside the `posthog` package, so it follows that package's version rather than its own. A minor or patch release of `posthog` doesn't change the `posthog.mcp` API in a breaking way, and doesn't rename or remove a `$mcp_*` event or property, change its type, or change which requests send an event, so saved insights keep working across upgrades. It may add events and properties, and redact more of a captured value. The rules come from the [MCP analytics spec](https://github.com/PostHog/sdk-specs/blob/main/openspec/specs/mcp-analytics/spec.md), section "Event schema stability". + ## Defaults and opt-outs A valid echoed conversation handle takes precedence over transport sessions. A request that already carries a transport session or a PostHog session token does not mint a new handle or append a prompt-back block. Requests carrying neither use the conversation fallback.