AI wizard
Contents
Developers love the wizard: it's the fastest way to get a deep, correct integration of PostHog, with none of the hallucinations that come from naive agent-based attempts.
For users, it is a one-line CLI command which runs an AI agent that automatically instruments PostHog into their codebases.
The wizard's architecture
The wizard is a CLI tool that runs locally against developers' projects.
It wraps the Claude Agent SDK to perform the integration, reviewing project code and making edits as needed.
To direct the agent, the wizard uses the PostHog MCP server as a context provider. The MCP provides the agent with skills and resources, which include workflow prompts, documentation, and example code to improve the correctness and completeness of the integration.
MCP context packages are derived from the PostHog context mill repository, which includes example apps, documentation and prompts. The context mill repo generates a zip file and manifest that determine's the URIs and structure of the context packages. Updating the context mill repo will instantly update the MCP content.
Developing the wizard
Use the wizard workbench for local, end-to-end development of the wizard. The workbench can run the full wizard stack in local development mode, with hot reload where supported.
The workbench is also responsible for CI and testing the wizard across a matrix of test applications.
Setting up the workbench
Clone these repos:
- https://github.com/PostHog/wizard-workbench
- https://github.com/PostHog/context-mill
- https://github.com/PostHog/wizard
- https://github.com/PostHog/posthog (contains the MCP server)
Next, configure the workbench to run the wizard and its local dependencies. Read the README.md file in the wizard-workbench repository to get started and create a .env file with the paths to the dependent repos.
Open a terminal at the workbench root and run:
Using the MCP inspector
You'll want the link that looks like this from the mcp-inspector mprocs panel:
Access the link in your browser, set the transport type to Streamable HTTP, and set the URL to http://localhost:8787/mcp for local development. (Alternatively, you can also inspect the production MCP by setting the URL to https://mcp.posthog.com/mcp).
You'll need a PostHog API key to access the MCP server. Get one from the user API keys settings page. Open the Authentication tab and paste the key into the Bearer token field.
Hit connect and you'll see the MCP server's contents.