Skip to content

docs(mcp-analytics): document stateless Python (instrument() + PostHogMCP) - #18920

Merged
gesh merged 11 commits into
masterfrom
posthog-code/mcp-analytics-python-stateless-install
Jul 27, 2026
Merged

docs(mcp-analytics): document stateless Python (instrument() + PostHogMCP)#18920
gesh merged 11 commits into
masterfrom
posthog-code/mcp-analytics-python-stateless-install

Conversation

@gesh

@gesh gesh commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Documents stateless / multi-pod support in the Python MCP analytics SDK, across both integration paths:

  • installation.mdx — FastMCP + instrument() (automatic). Replaces the stale "session tokens are TypeScript-only" callout with one line: on a stateless FastMCP(stateless_http=True) server instrument() handles it automatically (no enableJsonResponse equivalent; JSON + SSE both work).
  • custom-servers.mdx — custom PostHogMCP dispatcher (manual). New "Stateless / multi-pod dispatchers" subsection: add PostHogMcpStatelessSessionMiddleware to your ASGI app and read get_mcp_session() into each capture_* call.

Backed by PostHog/posthog-python#761.

⚠️ Draft until a posthog release includes PostHog/posthog-python#761 — the APIs aren't on PyPI yet (latest 7.29.0).

Created with PostHog Code

@github-actions github-actions Bot added the docs Improvements or additions to product documentation, "Docs" label Jul 24, 2026
@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Jul 27, 2026 12:21PM

@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Vale prose linter → found 40 errors, 18 warnings, 1 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/mcp-analytics/custom-servers.mdx — 15 errors, 5 warnings, 1 suggestions
Line Severity Message Rule
7:124 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
7:248 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
7:425 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
9:183 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
9:233 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
9:618 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
31:91 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
35:81 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
70:137 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
83:134 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
89:83 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
91:16 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
92:45 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
93:97 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
95:74 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
95:120 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
110:187 warning 'args' is a possible misspelling. PostHogBase.Spelling
149:158 warning 'kwargs' is a possible misspelling. PostHogBase.Spelling
149:405 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
153:172 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
175:84 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
contents/docs/mcp-analytics/installation.mdx — 25 errors, 13 warnings, 0 suggestions
Line Severity Message Rule
16:64 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
18:14 warning Use 'project token' instead of 'project API key'. The project token (phc_) is not an API key. PostHogBase.ProjectToken
36:211 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
40:280 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
40:318 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
64:110 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
87:51 warning Use the Oxford comma before 'and' or 'or' in a list of three or more items. PostHogBase.OxfordComma
117:48 warning 'OAuth' is a possible misspelling. PostHogBase.Spelling
132:1 warning 'untrusted' is a possible misspelling. PostHogBase.Spelling
143:106 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
167:213 warning Use 'MCP' instead of 'mcp'. Vale.Terms
167:242 warning 'mutator' is a possible misspelling. PostHogBase.Spelling
169:130 warning 'mutator' is a possible misspelling. PostHogBase.Spelling
181:51 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
183:161 warning Use 'ID' instead of 'id'. Vale.Terms
183:279 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
185:5 warning 'Streamable' is a possible misspelling. PostHogBase.Spelling
198:5 warning 'If you must stream (SSE)' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
220:269 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
230:70 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
235:4 warning 'jlowin's' is a possible misspelling. PostHogBase.Spelling
268:105 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
277:77 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
278:59 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
279:48 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
280:53 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
285:59 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
287:59 warning 'jlowin's' is a possible misspelling. PostHogBase.Spelling
295:38 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
305:160 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
314:137 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
324:75 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
331:93 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
333:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
335:76 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
336:77 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
357:115 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
369:136 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash

@gesh
gesh force-pushed the posthog-code/mcp-analytics-python-stateless-install branch from 6081bf2 to 2976069 Compare July 24, 2026 15:31
@gesh gesh changed the title docs(mcp-analytics): document stateless Python servers docs(mcp-analytics): note Python session tokens on stateless servers Jul 24, 2026
@gesh
docs(mcp-analytics): note Python session tokens on stateless servers
98680c4 
The stateless section's Python note said session tokens were TypeScript-only.
They work in Python too: instrument() auto-wires the mint into FastMCP's
streamable_http_app()/sse_app() factories (stateless_http), with no
enableJsonResponse equivalent (mints from an ASGI layer; JSON + SSE).
Replace the FYI callout with one concise line.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
gesh force-pushed the posthog-code/mcp-analytics-python-stateless-install branch from 2976069 to 98680c4 Compare July 24, 2026 15:35
@gesh gesh changed the title docs(mcp-analytics): note Python session tokens on stateless servers docs(mcp-analytics): note stateless session-token support for Python Jul 24, 2026
@gesh gesh changed the title docs(mcp-analytics): note stateless session-token support for Python docs(mcp-analytics): stateless Python — FastMCP + instrument() path (installation) Jul 24, 2026
@gesh gesh mentioned this pull request Jul 24, 2026
Closed
@gesh
docs(mcp-analytics): stateless note for the PostHogMCP custom dispatcher
06d50fe 
Add a "Stateless / multi-pod dispatchers" subsection to the Python part of
Custom servers: add PostHogMcpStatelessSessionMiddleware to your ASGI app and
feed get_mcp_session() into the capture_* calls so $session_id + the client
harness stay consistent across pods.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh gesh changed the title docs(mcp-analytics): stateless Python — FastMCP + instrument() path (installation) docs(mcp-analytics): document stateless Python (instrument() + PostHogMCP) Jul 24, 2026
@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

6.75 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 16.26 MiB (no change) report-only 1985
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 929.8 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 742.0 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.cjs.js 364.8 KiB
./src/hooks/useCustomers.tsx + 54 modules 355.1 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 121 modules 282.8 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules 272.1 KiB
./node_modules/.pnpm/framer-motion@10.18.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/dom/motion.mjs + 109 modules 253.9 KiB
./node_modules/.pnpm/d3@7.9.0/node_modules/d3/src/index.js + 208 modules 247.4 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules 240.1 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@gesh
gesh marked this pull request as ready for review July 27, 2026 09:38
gesh and others added 9 commits July 27, 2026 13:38
@gesh
docs(mcp-analytics): fix capture_tool_call kwargs in stateless example
a0aaed7 
capture_tool_call has no client_name/client_version params — the recovered
client identity goes via $mcp_client_* properties (matching the TS example
in the same doc). Verified against the published posthog 7.30.0.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
docs(mcp-analytics): clarify where stateless tokens are zero-config v…
19e9511 
…s manual

The auto-wire is FastMCP-family-specific (it wraps app factories only FastMCP
exposes). Reword the Python note: zero-config on FastMCP (official + jlowin 2.0)
via stateless_http; add the middleware yourself for a low-level Server or a
custom PostHogMCP dispatcher, where you build the ASGI app.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
docs(mcp-analytics): give Python its own stateless subsection
832860e 
The Python note previously sat under "### When you can't use a session token"
— contradicting that heading, since Python session tokens DO work. Move it to
its own "### Python" subsection alongside the TypeScript-specific ones.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
docs(mcp-analytics): consolidate stateless Python into the Python sec…
4dea652 
…tion

Avoid two Python sections. Drop the `### Python` note under the (TypeScript)
stateless section and add a self-contained `### Stateless and multi-pod servers`
subsection inside `## Python` — with runnable FastMCP + middleware snippets.
The TS section now points Python readers down; both languages are discoverable.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
docs(mcp-analytics): drop redundant Python pointer in stateless section
3c6b422 
The dedicated ## Python section now has its own stateless subsection, and no
other TypeScript section carries a "Python? see below" pointer — so the line
was redundant and inconsistent. Removed.

Generated-By: PostHog Code
Task-Id: f44ec5e0-b836-4d13-98c4-c26887dd7ec2
@gesh
Merge branch 'master' into posthog-code/mcp-analytics-python-stateles…
4bbfc94 
…s-install
@posthog @gesh
chore(visual): update playwright baselines
c6286f2 
2 updated
Run: 1e15d7e5-bdd9-40e8-998d-30b6a71cf1f7

Co-authored-by: gesh <6430745+gesh@users.noreply.github.com>
@posthog @gesh
chore(visual): update playwright baselines
10da0c0 
1 updated
Run: 78ce28b8-34bd-4163-ad1e-0a42fd40a02b

Co-authored-by: gesh <6430745+gesh@users.noreply.github.com>
@posthog @gesh
chore(visual): update playwright baselines
24d00f7 
1 updated
Run: 9e5b7454-d2c0-4edd-8311-f561104bc799

Co-authored-by: gesh <6430745+gesh@users.noreply.github.com>
@gesh
gesh merged commit 76657ca into master Jul 27, 2026
18 of 19 checks passed
@gesh
gesh deleted the posthog-code/mcp-analytics-python-stateless-install branch July 27, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gesh