:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp): add codebase install skill and api_host on project-get (#122384)
Rafael Audibertaf7edf64d7d0
diff --git a/frontend/src/generated/core/api.schemas.ts b/frontend/src/generated/core/api.schemas.tsindex 5a655be148bd..3cc8cf88b17c 100644--- a/frontend/src/generated/core/api.schemas.ts+++ b/frontend/src/generated/core/api.schemas.ts@@ -3676,6 +3676,8 @@ export interface ProjectBackwardCompatApi {readonly managed_viewsets: ProjectBackwardCompatApiManagedViewsets/** Which table this project's feature flag usage data is read from. PostHog sets it for the whole organization. 0 reads the events table. 1 and 2 read the flag_evaluations table. */readonly flag_evaluations_mode: FlagEvaluationsModeEnumApi+ /** Host the PostHog SDKs send events to, set as their `api_host` option. It is `https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, and the instance URL when self-hosted. */+ readonly api_host: stringrevenue_analytics_config?: TeamRevenueAnalyticsConfigApimarketing_analytics_config?: TeamMarketingAnalyticsConfigApicustomer_analytics_config?: TeamCustomerAnalyticsConfigApi@@ -4564,6 +4566,8 @@ export interface PatchedProjectBackwardCompatApi {readonly managed_viewsets?: PatchedProjectBackwardCompatApiManagedViewsets/** Which table this project's feature flag usage data is read from. PostHog sets it for the whole organization. 0 reads the events table. 1 and 2 read the flag_evaluations table. */readonly flag_evaluations_mode?: FlagEvaluationsModeEnumApi+ /** Host the PostHog SDKs send events to, set as their `api_host` option. It is `https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, and the instance URL when self-hosted. */+ readonly api_host?: stringrevenue_analytics_config?: TeamRevenueAnalyticsConfigApimarketing_analytics_config?: TeamMarketingAnalyticsConfigApicustomer_analytics_config?: TeamCustomerAnalyticsConfigApidiff --git a/posthog/api/project.py b/posthog/api/project.pyindex d56955e467ec..d3038e204a49 100644--- a/posthog/api/project.py+++ b/posthog/api/project.py@@ -19,6 +19,7 @@ from rest_framework.permissions import BasePermission, IsAuthenticatedfrom posthog.schema import ProductKey+from posthog import cloud_utilsfrom posthog.api import project_tagsfrom posthog.api.project_secret_api_key import _enforce_caller_holds_scopesfrom posthog.api.routing import TeamAndOrgViewSetMixin@@ -641,6 +642,13 @@ class ProjectBackwardCompatSerializer(# These are @property attrs on Team, not Django model fields — declare explicitly so drf-spectacular can resolve themdefault_modifiers = serializers.DictField(read_only=True) # Compat with TeamSerializerperson_on_events_querying_enabled = serializers.BooleanField(read_only=True) # Compat with TeamSerializer+ api_host = serializers.SerializerMethodField( # Compat with TeamSerializer+ help_text=(+ "Host the PostHog SDKs send events to, set as their `api_host` option. It is "+ "`https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, "+ "and the instance URL when self-hosted."+ )+ )heatmaps_screenshot_secret = serializers.SerializerMethodField(help_text=("Value this project's heatmap screenshots send as a cookie scoped to your domain, "@@ -803,6 +811,7 @@ class ProjectBackwardCompatSerializer("user_access_level", # Compat with TeamSerializer"managed_viewsets", # Compat with TeamSerializer"flag_evaluations_mode", # Compat with TeamSerializer+ "api_host", # Compat with TeamSerializer"revenue_analytics_config", # Compat with TeamSerializer"marketing_analytics_config", # Compat with TeamSerializer"customer_analytics_config", # Compat with TeamSerializer@@ -845,6 +854,7 @@ class ProjectBackwardCompatSerializer("user_access_level","managed_viewsets","flag_evaluations_mode",+ "api_host",)team_passthrough_fields = {@@ -1061,6 +1071,9 @@ class ProjectBackwardCompatSerializer(def get_live_events_token(self, project: Project) -> Optional[str]:return live_events_token_for_request(project.passthrough_team, self.context.get("request"))+ def get_api_host(self, project: Project) -> str:+ return cloud_utils.get_api_host()+@extend_schema_field(serializers.CharField(allow_null=True))def get_heatmaps_screenshot_secret(self, project: Project) -> Optional[str]:return heatmaps_screenshot_secret_for_reader(project.passthrough_team, self.user_permissions)diff --git a/posthog/api/team/team_serializer.py b/posthog/api/team/team_serializer.pyindex e4262b58aaff..20aa1894fad4 100644--- a/posthog/api/team/team_serializer.py+++ b/posthog/api/team/team_serializer.py@@ -9,6 +9,7 @@ from drf_spectacular.utils import extend_schema_fieldfrom opentelemetry import tracefrom rest_framework import exceptions, serializers+from posthog import cloud_utilsfrom posthog.api.scoped_related_fields import TeamScopedPrimaryKeyRelatedFieldfrom posthog.api.utils import validate_authorized_url_wildcardsfrom posthog.constants import AvailableFeature@@ -77,6 +78,13 @@ class TeamSerializer(serializers.ModelSerializer, UserPermissionsSerializerMixin))available_setup_task_ids = serializers.SerializerMethodField()+ api_host = serializers.SerializerMethodField(+ help_text=(+ "Host the PostHog SDKs send events to, set as their `api_host` option. It is "+ "`https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, "+ "and the instance URL when self-hosted."+ )+ )heatmaps_screenshot_secret = serializers.SerializerMethodField(help_text=("Value this project's heatmap screenshots send as a cookie scoped to your domain, "@@ -135,6 +143,7 @@ class TeamSerializer(serializers.ModelSerializer, UserPermissionsSerializerMixin"managed_viewsets","flag_evaluations_mode","available_setup_task_ids",+ "api_host",)read_only_fields = (@@ -159,6 +168,7 @@ class TeamSerializer(serializers.ModelSerializer, UserPermissionsSerializerMixin"managed_viewsets","flag_evaluations_mode","available_setup_task_ids",+ "api_host",)def get_fields(self) -> dict[str, serializers.Field]:@@ -200,6 +210,9 @@ class TeamSerializer(serializers.ModelSerializer, UserPermissionsSerializerMixindef get_live_events_token(self, team: Team) -> str | None:return live_events.live_events_token_for_request(team, self.context.get("request"))+ def get_api_host(self, team: Team) -> str:+ return cloud_utils.get_api_host()+@extend_schema_field(serializers.CharField(allow_null=True))def get_heatmaps_screenshot_secret(self, team: Team) -> str | None:return settings_validation.heatmaps_screenshot_secret_for_reader(team, self.user_permissions)diff --git a/products/desktop/packages/api-client/src/generated.ts b/products/desktop/packages/api-client/src/generated.tsindex 689cdabe9978..f08381b212f0 100644--- a/products/desktop/packages/api-client/src/generated.ts+++ b/products/desktop/packages/api-client/src/generated.ts@@ -20486,6 +20486,10 @@ export namespace Schemas {* Which table this project's feature flag usage data is read from. PostHog sets it for the whole organization. 0 reads the events table. 1 and 2 read the flag_evaluations table.*/flag_evaluations_mode: FlagEvaluationsModeEnum & unknown;+ /**+ * Host the PostHog SDKs send events to, set as their `api_host` option. It is `https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, and the instance URL when self-hosted.+ */+ api_host: string;/*** A project and its settings, including the settings that live on its passthrough Team.*diff --git a/products/wizard/skills/installing-posthog-from-chat/SKILL.md b/products/wizard/skills/installing-posthog-from-chat/SKILL.mdindex e071f5796478..e198fec6f7a1 100644--- a/products/wizard/skills/installing-posthog-from-chat/SKILL.md+++ b/products/wizard/skills/installing-posthog-from-chat/SKILL.md@@ -2,10 +2,12 @@name: installing-posthog-from-chatdescription: >-Set up PostHog in a user's GitHub repository from a chat, without a terminal. Wizard, PostHog's- setup agent, runs in the cloud, adds the SDK and first events, and opens a pull request. Use when- a user in ChatGPT, Claude, or another chat client asks to install, add, or set up PostHog in- their app or repository, or asks for a pull request that adds PostHog. Covers connecting GitHub,- picking the repository, starting the run, polling it, and sharing the pull request.+ setup agent, runs in the cloud, adds the SDK and first events, and opens a pull request. Use only+ when you can't read or edit the user's code, which is common in web chat apps such as ChatGPT on the+ web or Claude on the web. Typical requests: install, add, or set up PostHog in their app or+ repository, or open a pull request that adds PostHog. When you're working in the user's repository, use+ installing-posthog-in-a-codebase instead. Covers connecting GitHub, picking the repository, starting+ the run, polling it, and sharing the pull request.---# Installing PostHog from chatdiff --git a/products/wizard/skills/installing-posthog-in-a-codebase/SKILL.md b/products/wizard/skills/installing-posthog-in-a-codebase/SKILL.mdnew file mode 100644index 000000000000..543400054ebe--- /dev/null+++ b/products/wizard/skills/installing-posthog-in-a-codebase/SKILL.md@@ -0,0 +1,93 @@+---+name: installing-posthog-in-a-codebase+description: >-+ Install and configure a PostHog SDK in a repository you can read and edit, following PostHog's docs for+ the framework. Use when a user working in their codebase asks to add, install, or set up PostHog, product+ analytics, session replay, or a PostHog SDK. Covers finding the right docs page, installing the latest+ package, getting the project token and ingestion host from project-get, keeping them in the env file,+ server-side setup, identifying users, and verifying the change. If you can't access the user's code, as is+ common in ChatGPT on the web or Claude on the web, use installing-posthog-from-chat instead.+---++# Installing PostHog in a codebase++Use this skill when you can read and edit the user's code.+If you can't access their code, as is common in ChatGPT on the web or Claude on the web, use `installing-posthog-from-chat`.++PostHog's docs are the source of truth for each SDK's setup.+Init options, file locations and recommended settings change between SDK releases, so read the docs page for the framework before you write code, and follow it rather than what you remember.++## 1. Find the framework and read its docs++Detect the framework from the manifest files (`package.json`, `pyproject.toml`, `requirements.txt`, `Gemfile`, `composer.json`, `go.mod`, and so on) and the app's entry points.+A web app with its own backend usually needs a client SDK and a server SDK, so read both pages.++| Framework | Docs page |+| ------------------------------ | ---------------------------------------------------- |+| JavaScript web (any framework) | https://posthog.com/docs/libraries/js.md |+| React, including Vite apps | https://posthog.com/docs/libraries/react.md |+| Next.js | https://posthog.com/docs/libraries/next-js.md |+| Vue.js | https://posthog.com/docs/libraries/vue-js.md |+| Nuxt | https://posthog.com/docs/libraries/nuxt-js.md |+| Svelte and SvelteKit | https://posthog.com/docs/libraries/svelte.md |+| Angular | https://posthog.com/docs/libraries/angular.md |+| Astro | https://posthog.com/docs/libraries/astro.md |+| Remix | https://posthog.com/docs/libraries/remix.md |+| React Router | https://posthog.com/docs/libraries/react-router.md |+| TanStack Start | https://posthog.com/docs/libraries/tanstack-start.md |+| Node.js, including Express | https://posthog.com/docs/libraries/node.md |+| Python, including FastAPI | https://posthog.com/docs/libraries/python.md |+| Django | https://posthog.com/docs/libraries/django.md |+| Flask | https://posthog.com/docs/libraries/flask.md |+| Ruby | https://posthog.com/docs/libraries/ruby.md |+| Ruby on Rails | https://posthog.com/docs/libraries/ruby-on-rails.md |+| PHP | https://posthog.com/docs/libraries/php.md |+| Laravel | https://posthog.com/docs/libraries/laravel.md |+| Go | https://posthog.com/docs/libraries/go.md |+| Java | https://posthog.com/docs/libraries/java.md |+| .NET | https://posthog.com/docs/libraries/dotnet.md |+| Elixir | https://posthog.com/docs/libraries/elixir.md |+| Rust | https://posthog.com/docs/libraries/rust.md |+| React Native | https://posthog.com/docs/libraries/react-native.md |+| Flutter | https://posthog.com/docs/libraries/flutter.md |+| iOS | https://posthog.com/docs/libraries/ios.md |+| Android | https://posthog.com/docs/libraries/android.md |++For a framework that isn't listed, call `docs-search` with the framework name.++## 2. Install the latest SDK++Add each package with the project's own package manager and no version, for example `npm install posthog-js`, `pnpm add posthog-node`, `uv add posthog` or `bundle add posthog-ruby`.+That resolves the newest release.+Don't type a version into the manifest from memory, because that pins an old release.++In a monorepo, install into the package that runs the app, not the workspace root.++## 3. Get the token and host++Call `project-get` without an ID.+Use `api_token` as the project token and `api_host` as the SDK's host option.++- Read both from environment variables in code, using the names the docs page uses (for example `NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN` and `NEXT_PUBLIC_POSTHOG_HOST`).+- Write the real values to the env file the framework loads, such as `.env.local` or `.env`. If the project has an example env file, add the variable names there with empty values.+- Never hard-code the token or the host in source files, and never use them as fallback defaults in code.++## 4. Initialize as the docs show++- Initialize the SDK once, in the place the docs page names. Don't add a second initialization elsewhere.+- For `posthog-js`, set `defaults` to the date the docs page shows. It selects the newest set of recommended settings, so don't take a date from memory.+- For a backend SDK in a long-running server, create one client for the process, reuse it, and shut it down when the process exits. Don't create a client per request.+- In serverless or edge handlers (for example Next.js route handlers on Vercel, or AWS Lambda), the runtime can freeze as soon as the response is sent, so queued events are lost. Flush before the handler returns: await `flush()` on a reused client, or use the platform's `waitUntil`, as the docs page describes.+- For a server-rendered app (Django, Rails, Laravel and similar), add the server SDK as well as the browser snippet.++## 5. Identify users++If the app has login, call `identify` after login with a stable user ID from the auth system, such as the database ID, not an email address or display name.+Call `reset()` on logout.+Send server-side events with the same distinct ID, so client and server events land on the same person.++## 6. Verify++Run the project's build, type check or tests, and fix anything your change broke.+If you can run the app, load a page and check that events arrive with `read-data-schema` or `execute-sql`.+Tell the user which environment variables to add in their hosting provider before they deploy.diff --git a/services/mcp/definitions/core.yaml b/services/mcp/definitions/core.yamlindex fefb44989b7d..e5065bc8ce3b 100644--- a/services/mcp/definitions/core.yaml+++ b/services/mcp/definitions/core.yaml@@ -274,8 +274,14 @@ tools:title: Get projectdescription: |Retrieve a project and its settings. Omit the ID to get the caller's active project. This is the one tool- that returns the project API token, which is safe to put in client-side code. Project listing, project- updates and the session context leave it out, so ask for a single project when you need the token.+ that returns the project API token. Project listing, project updates and the session context leave it out,+ so ask for a single project when you need the token.++ When you install or configure a PostHog SDK, use `api_token` as the project token and `api_host` as the+ SDK's `api_host` (the ingestion host for this project's region). The token is public, so it can ship in+ client-side bundles, but treat it as configuration: read it from the app's environment variable and write+ the real value to the local env file (for example `.env.local` or `.env`). Never hard-code the token or the+ host in source files, and never use them as fallback defaults.param_overrides:id:description: Project ID. If omitted, returns the caller's active project.diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 28ad75c6d9a5..581951450852 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -11163,7 +11163,7 @@}},"project-get": {- "description": "Retrieve a project and its settings. Omit the ID to get the caller's active project. This is the one tool\nthat returns the project API token, which is safe to put in client-side code. Project listing, project\nupdates and the session context leave it out, so ask for a single project when you need the token.",+ "description": "Retrieve a project and its settings. Omit the ID to get the caller's active project. This is the one tool\nthat returns the project API token. Project listing, project updates and the session context leave it out,\nso ask for a single project when you need the token.\n\nWhen you install or configure a PostHog SDK, use `api_token` as the project token and `api_host` as the\nSDK's `api_host` (the ingestion host for this project's region). The token is public, so it can ship in\nclient-side bundles, but treat it as configuration: read it from the app's environment variable and write\nthe real value to the local env file (for example `.env.local` or `.env`). Never hard-code the token or the\nhost in source files, and never use them as fallback defaults.","category": "Core","feature": "core","summary": "Get project",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex c313b5116576..07a98a946538 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -11792,7 +11792,7 @@}},"project-get": {- "description": "Retrieve a project and its settings. Omit the ID to get the caller's active project. This is the one tool\nthat returns the project API token, which is safe to put in client-side code. Project listing, project\nupdates and the session context leave it out, so ask for a single project when you need the token.",+ "description": "Retrieve a project and its settings. Omit the ID to get the caller's active project. This is the one tool\nthat returns the project API token. Project listing, project updates and the session context leave it out,\nso ask for a single project when you need the token.\n\nWhen you install or configure a PostHog SDK, use `api_token` as the project token and `api_host` as the\nSDK's `api_host` (the ingestion host for this project's region). The token is public, so it can ship in\nclient-side bundles, but treat it as configuration: read it from the app's environment variable and write\nthe real value to the local env file (for example `.env.local` or `.env`). Never hard-code the token or the\nhost in source files, and never use them as fallback defaults.","category": "Core","feature": "core","summary": "Get project",diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 1b5252ceb0ae..57c7ae7c0cef 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -88276,6 +88276,8 @@ export namespace Schemas {readonly managed_viewsets?: PatchedProjectBackwardCompatManagedViewsets;/** Which table this project's feature flag usage data is read from. PostHog sets it for the whole organization. 0 reads the events table. 1 and 2 read the flag_evaluations table. */readonly flag_evaluations_mode?: FlagEvaluationsModeEnum;+ /** Host the PostHog SDKs send events to, set as their `api_host` option. It is `https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, and the instance URL when self-hosted. */+ readonly api_host?: string;revenue_analytics_config?: TeamRevenueAnalyticsConfig;marketing_analytics_config?: TeamMarketingAnalyticsConfig;customer_analytics_config?: TeamCustomerAnalyticsConfig;@@ -93718,6 +93720,8 @@ export namespace Schemas {readonly managed_viewsets: ProjectBackwardCompatManagedViewsets;/** Which table this project's feature flag usage data is read from. PostHog sets it for the whole organization. 0 reads the events table. 1 and 2 read the flag_evaluations table. */readonly flag_evaluations_mode: FlagEvaluationsModeEnum;+ /** Host the PostHog SDKs send events to, set as their `api_host` option. It is `https://us.i.posthog.com` on US Cloud, `https://eu.i.posthog.com` on EU Cloud, and the instance URL when self-hosted. */+ readonly api_host: string;revenue_analytics_config?: TeamRevenueAnalyticsConfig;marketing_analytics_config?: TeamMarketingAnalyticsConfig;customer_analytics_config?: TeamCustomerAnalyticsConfig;