: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
fix(mcp): let agents check the project limit before project-create (#119135)
posthog[bot]210dd5ee3ad4
diff --git a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md b/docs/published/handbook/engineering/ai/implementing-mcp-tools.mdindex 3059da1020af..179afa1e3822 100644--- a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md+++ b/docs/published/handbook/engineering/ai/implementing-mcp-tools.md@@ -577,6 +577,8 @@ Product teams own their definitions and control which operations are exposed asUnknown keys are rejected at build time (Zod `.strict()`) to catch typos early.+ Keep plan-limit guidance aligned with backend permissions. For `project-create`, `organization-get` exposes the plan feature limits and each team's `project_id` and `is_demo`. Count distinct project IDs among non-demo teams; neither the project list length nor the environment count matches the backend rule. Visible lists can omit inaccessible projects, so a count below the limit does not guarantee permission. The backend remains authoritative.+For list tools with a UI app, set `response.text_include` to the dot-path fields an agentneeds from each result row. This adds a compact text response for clients that cannot read`structuredContent`, while preserving the full structured payload for the app and explicitdiff --git a/products/platform_features/mcp/tools.yaml b/products/platform_features/mcp/tools.yamlindex 2c0453ea9e3f..413de12a369b 100644--- a/products/platform_features/mcp/tools.yaml+++ b/products/platform_features/mcp/tools.yaml@@ -386,8 +386,11 @@ tools:idempotent: truetitle: Get organization details.description: >- Get details of an organization by ID including name, membership level, member count, teams, and projects. If- no ID is provided, returns the active organization.+ Get details of an organization by ID including name, membership level, member count, teams, projects, and+ the plan features available to it. Each entry in `available_product_features` has a `key` and a `limit`. For+ example, `organizations_projects` gives the maximum number of non-demo projects. Teams include `project_id`+ and `is_demo` so multiple environments of one project count once and demo projects can be excluded. These+ lists include only projects visible to the caller. If no ID is provided, returns the active organization.param_overrides:id:description: |@@ -406,8 +409,11 @@ tools:- teams.*.id- teams.*.name- teams.*.project_id+ - teams.*.is_demo- projects.*.id- projects.*.name+ - available_product_features.*.key+ - available_product_features.*.limitorganizations-list:operation: listenabled: truediff --git a/services/mcp/definitions/core.yaml b/services/mcp/definitions/core.yamlindex 21094fe3ac72..fefb44989b7d 100644--- a/services/mcp/definitions/core.yaml+++ b/services/mcp/definitions/core.yaml@@ -234,10 +234,20 @@ tools:title: Create projectdescription: >Create a project in the caller's active organization. A project is a separate data container with its own- API token, so use it to keep unrelated data apart, for example staging and production. Creating a project- adds to the organization's plan usage, so always confirm the name with the user before calling this. The new- project does not become active: call `switch-project` with the returned ID to work in it. The response- carries the project API token, which is safe to put in client-side code.+ API token, so use it to keep unrelated data apart, for example staging and production. The organization's+ plan limits how many projects it can have, and only organization admins can create projects unless the+ organization lets members do it. Before you propose a new project, call `organization-get`. In its `teams`,+ count distinct `project_id` values only for entries with `is_demo: false`; demo projects do not count and+ multiple environments of one project count once. Do not use the length of `projects` or `teams`. Compare+ that count with the `organizations_projects` entry in `available_product_features`: its `limit` is the+ maximum number of non-demo projects, and a null `limit` means the plan sets no limit. If the entry is+ missing, the organization can have only one non-demo project. If the count reaches the limit, tell the user+ and offer an existing project or a plan upgrade instead of calling this. Visible lists may be incomplete, so+ a lower count does not guarantee permission; the backend makes the final decision. Always confirm the name+ with the user before calling this. If this call fails with a permission error, do not call it again: give+ the user the reason from the error. The new project does not become active: call `switch-project` with the+ returned ID to work in it. The response carries the project API token, which is safe to put in client-side+ code.include_params:- nameparam_overrides:diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 183d95cf682e..e7d03d67528f 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -10131,7 +10131,7 @@"feature_entitlement": "2fa_enforcement"},"organization-get": {- "description": "Get details of an organization by ID including name, membership level, member count, teams, and projects. If no ID is provided, returns the active organization.",+ "description": "Get details of an organization by ID including name, membership level, member count, teams, projects, and the plan features available to it. Each entry in `available_product_features` has a `key` and a `limit`. For example, `organizations_projects` gives the maximum number of non-demo projects. Teams include `project_id` and `is_demo` so multiple environments of one project count once and demo projects can be excluded. These lists include only projects visible to the caller. If no ID is provided, returns the active organization.","category": "Platform Features","feature": "platform_features","summary": "Get organization details.",@@ -10305,7 +10305,7 @@}},"project-create": {- "description": "Create a project in the caller's active organization. A project is a separate data container with its own API token, so use it to keep unrelated data apart, for example staging and production. Creating a project adds to the organization's plan usage, so always confirm the name with the user before calling this. The new project does not become active: call `switch-project` with the returned ID to work in it. The response carries the project API token, which is safe to put in client-side code.",+ "description": "Create a project in the caller's active organization. A project is a separate data container with its own API token, so use it to keep unrelated data apart, for example staging and production. The organization's plan limits how many projects it can have, and only organization admins can create projects unless the organization lets members do it. Before you propose a new project, call `organization-get`. In its `teams`, count distinct `project_id` values only for entries with `is_demo: false`; demo projects do not count and multiple environments of one project count once. Do not use the length of `projects` or `teams`. Compare that count with the `organizations_projects` entry in `available_product_features`: its `limit` is the maximum number of non-demo projects, and a null `limit` means the plan sets no limit. If the entry is missing, the organization can have only one non-demo project. If the count reaches the limit, tell the user and offer an existing project or a plan upgrade instead of calling this. Visible lists may be incomplete, so a lower count does not guarantee permission; the backend makes the final decision. Always confirm the name with the user before calling this. If this call fails with a permission error, do not call it again: give the user the reason from the error. The new project does not become active: call `switch-project` with the returned ID to work in it. The response carries the project API token, which is safe to put in client-side code.","category": "Core","feature": "core","summary": "Create project",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 76912baca4ed..3b2fc0ff6769 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -10666,7 +10666,7 @@"feature_entitlement": "2fa_enforcement"},"organization-get": {- "description": "Get details of an organization by ID including name, membership level, member count, teams, and projects. If no ID is provided, returns the active organization.",+ "description": "Get details of an organization by ID including name, membership level, member count, teams, projects, and the plan features available to it. Each entry in `available_product_features` has a `key` and a `limit`. For example, `organizations_projects` gives the maximum number of non-demo projects. Teams include `project_id` and `is_demo` so multiple environments of one project count once and demo projects can be excluded. These lists include only projects visible to the caller. If no ID is provided, returns the active organization.","category": "Platform Features","feature": "platform_features","summary": "Get organization details.",@@ -10883,7 +10883,7 @@}},"project-create": {- "description": "Create a project in the caller's active organization. A project is a separate data container with its own API token, so use it to keep unrelated data apart, for example staging and production. Creating a project adds to the organization's plan usage, so always confirm the name with the user before calling this. The new project does not become active: call `switch-project` with the returned ID to work in it. The response carries the project API token, which is safe to put in client-side code.",+ "description": "Create a project in the caller's active organization. A project is a separate data container with its own API token, so use it to keep unrelated data apart, for example staging and production. The organization's plan limits how many projects it can have, and only organization admins can create projects unless the organization lets members do it. Before you propose a new project, call `organization-get`. In its `teams`, count distinct `project_id` values only for entries with `is_demo: false`; demo projects do not count and multiple environments of one project count once. Do not use the length of `projects` or `teams`. Compare that count with the `organizations_projects` entry in `available_product_features`: its `limit` is the maximum number of non-demo projects, and a null `limit` means the plan sets no limit. If the entry is missing, the organization can have only one non-demo project. If the count reaches the limit, tell the user and offer an existing project or a plan upgrade instead of calling this. Visible lists may be incomplete, so a lower count does not guarantee permission; the backend makes the final decision. Always confirm the name with the user before calling this. If this call fails with a permission error, do not call it again: give the user the reason from the error. The new project does not become active: call `switch-project` with the returned ID to work in it. The response carries the project API token, which is safe to put in client-side code.","category": "Core","feature": "core","summary": "Create project",diff --git a/services/mcp/src/tools/generated/platform_features.ts b/services/mcp/src/tools/generated/platform_features.tsindex 8cf34e45494e..b874dc8791d2 100644--- a/services/mcp/src/tools/generated/platform_features.ts+++ b/services/mcp/src/tools/generated/platform_features.ts@@ -748,8 +748,11 @@ const organizationGet = (): ToolBase<ReturnType<typeof OrganizationGetSchema>, S'teams.*.id','teams.*.name','teams.*.project_id',+ 'teams.*.is_demo','projects.*.id','projects.*.name',+ 'available_product_features.*.key',+ 'available_product_features.*.limit',]) as typeof resultreturn filtered},diff --git a/services/mcp/tests/unit/project-create.test.ts b/services/mcp/tests/unit/project-create.test.tsindex 48ae10ad7bdb..a03b3235d474 100644--- a/services/mcp/tests/unit/project-create.test.ts+++ b/services/mcp/tests/unit/project-create.test.ts@@ -1,6 +1,7 @@import { describe, expect, it, vi } from 'vitest'import { getToolsFromContext } from '@/tools'+import { GENERATED_TOOL_MAP } from '@/tools/generated'import { GENERATED_TOOLS } from '@/tools/generated/core'import type { Context } from '@/tools/types'@@ -67,6 +68,43 @@ describe('project-create', () => {})})+ it('returns the plan limit and distinguishes demo projects from multiple environments', async () => {+ const request = vi.fn().mockResolvedValue({+ id: 'org-abc',+ name: 'Example',+ projects: [+ { id: 1, name: 'Default' },+ { id: 2, name: 'Demo' },+ ],+ teams: [+ { id: 11, project_id: 1, name: 'Production', is_demo: false, api_token: 'phc_example' },+ { id: 12, project_id: 1, name: 'Staging', is_demo: false },+ { id: 21, project_id: 2, name: 'Demo', is_demo: true },+ ],+ available_product_features: [+ { key: 'organizations_projects', name: 'Projects', limit: 2, unit: 'projects' },+ { key: 'group_analytics', name: 'Group analytics' },+ ],+ })++ const result = await GENERATED_TOOL_MAP['organization-get']!().handler(createMockContext(request), {})++ expect(result).toEqual({+ id: 'org-abc',+ name: 'Example',+ projects: [+ { id: 1, name: 'Default' },+ { id: 2, name: 'Demo' },+ ],+ teams: [+ { id: 11, project_id: 1, name: 'Production', is_demo: false },+ { id: 12, project_id: 1, name: 'Staging', is_demo: false },+ { id: 21, project_id: 2, name: 'Demo', is_demo: true },+ ],+ available_product_features: [{ key: 'organizations_projects', limit: 2 }, { key: 'group_analytics' }],+ })+ })+it.each([['project:write', true],['project:read', false],