Developing the wizard

Author: daniloc

contents/handbook/content/docs-runbook/developing-the-wizard.mdx

@@ -0,0 +1,73 @@
+---
+title: Developing the wizard
+sidebar: Handbook
+showTitle: true
+---
+
+Developers love the wizard: it's the fastest way to get a deep, correct integration of PostHog into their project, with none of the hallucinations that come from naive agent-based attempts.
+
+## The wizard's architecture
+
+The wizard is a CLI tool that runs locally in developers' projects.
+
+It wraps the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) to perform the integration, reviewing project code and making edits as needed.
+
+To direct the agent, the wizard uses the PostHog [MCP server](https://github.com/PostHog/posthog/tree/master/products/mcp) as a context provider. The MCP includes workflow prompts, documentation and example code to improve the correctness and completeness of the integration.
+
+MCP content is derived from the PostHog [examples repository](https://github.com/PostHog/examples), which includes code snippets, documentation and prompts. The examples repo generates a zip file and manifest that determine's the URIs and structure for `prompts` and `resources`. Updating the examples repo will instantly update the MCP content.
+
+## Developing the wizard
+
+Use these prompts to get your agent started.
+
+Get the repos:
+
+```md
+
+Clone these repositories:
+
+https://github.com/PostHog/wizard-workbench
+https://github.com/PostHog/examples
+https://github.com/PostHog/wizard
+
+(If you don't have it already, the PostHog repo includes the MCP server) https://github.com/PostHog/posthog
+
+```
+
+Configure the workbench to run the wizard and its local dependencies:
+
+```md
+
+Read the README.md file in the wizard-workbench repository. Configure a .env file with the paths to the repos.
+
+```
+
+With the workbench now configured, open a terminal at its root and run:
+
+```bash
+mprocs
+```
+
+This will start the workbench and all its dependencies:
+
+- Making a change to the examples repo will instantly update the MCP content. 
+- Editing the wizard's code will automatically rebuild and link the changes globally. Run it against any project on your machine with `wizard --local-mcp`.
+- Review the contents of the MCP server by selecting the **mcp-inspector** tab and opening the link it provides in your browser.
+
+## Using the MCP inspector
+
+You'll want the link that looks like this from the mcp-inspector tab:
+
+```
+http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=97e0ba...
+```
+
+Look for the text `Open inspector with token pre-filled.
+
+Access the link in your browser, set the transport type to **Streamable HTTP**, and set the URL to **http://localhost:8787/mcp**. (Alternatively, you can also inspect the production MCP by setting the URL to **https://mcp.posthog.com/mcp**).
+
+![MCP inspector](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/Screenshot_2025_12_17_at_4_04_47_PM_df53b1ea2b.png)
+
+You'll need a PostHog API key to access the MCP server. Get one from the [user API keys settings page](https://app.posthog.com/settings/user-api-keys?preset=mcp_server). Open the **Authentication** tab and paste the key into the **Bearer token** field.
+
+Hit connect and you'll see the MCP server's contents.

contents/handbook/content/docs-runbook/index.mdx

@@ -13,4 +13,5 @@ We've built out extensive tooling to help us write docs. This page records how t
 | [Onboarding docs](/handbook/content/docs-runbook/onboarding-docs) | How to create and maintain shared onboarding documentation between the in-app flow and website |
 | [SDK reference docs](/handbook/content/docs-runbook/sdk-reference-docs) | How SDK reference documentation is generated and maintained |
 | [API specification](/handbook/content/docs-runbook/api-specification) | How to create and maintain the API specification |
+| [Developing the wizard](/handbook/content/docs-runbook/developing-the-wizard) | How to develop and extend the onboarding wizard |