feat(mcp-store): personal/shared MCP installation scope

packages/api-client/src/generated.ts

@@ -9350,6 +9350,7 @@ export namespace Schemas {
   export type InsightsToolCall = { query: string; insight_type: InsightTypeEnum };
   export type InstallCustomAuthTypeEnum = "api_key" | "oauth";
   export type InstallSourceEnum = "posthog" | "posthog-code";
+  export type MCPInstallationScopeEnum = "personal" | "shared";
   export type InstallCustom = {
     name: string;
     url: string;
@@ -9360,12 +9361,14 @@ export namespace Schemas {
     client_secret?: string | undefined;
     install_source?: (InstallSourceEnum & unknown) | undefined;
     posthog_code_callback_url?: string | undefined;
+    scope?: (MCPInstallationScopeEnum & unknown) | undefined;
   };
   export type InstallTemplate = {
     template_id: string;
     api_key?: string | undefined;
     install_source?: (InstallSourceEnum & unknown) | undefined;
     posthog_code_callback_url?: string | undefined;
+    scope?: (MCPInstallationScopeEnum & unknown) | undefined;
   };
   export type IntegrationKindEnum =
     | "azure-blob"
@@ -9707,6 +9710,7 @@ export namespace Schemas {
     updated_at: string | null;
   };
   export type MCPAuthTypeEnum = "api_key" | "oauth";
+  export type MCPServerInstallationScopeEnum = "personal" | "shared";
   export type MCPServerInstallation = {
     id: string;
     template_id: string | null;
@@ -9717,6 +9721,8 @@ export namespace Schemas {
     description?: string | undefined;
     auth_type?: MCPAuthTypeEnum | undefined;
     is_enabled?: boolean | undefined;
+    scope?: MCPServerInstallationScopeEnum | undefined;
+    is_owner?: boolean | undefined;
     needs_reauth: boolean;
     pending_oauth: boolean;
     proxy_url: string;

packages/api-client/src/posthog-client.test.ts

@@ -361,6 +361,75 @@ describe("PostHogAPIClient", () => {
     });
   });
 
+  describe("share/unshare MCP installation", () => {
+    function makeClient(fetch: ReturnType<typeof vi.fn>) {
+      const client = new PostHogAPIClient(
+        "http://localhost:8000",
+        async () => "token",
+        async () => "token",
+        123,
+      );
+      (
+        client as unknown as {
+          api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
+        }
+      ).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
+      return client;
+    }
+
+    it.each([
+      ["shareMcpInstallation", "share"],
+      ["unshareMcpInstallation", "unshare"],
+    ] as const)(
+      "%s POSTs to the %s action and returns the installation",
+      async (method, action) => {
+        const installation = { id: "inst-1", scope: "shared" };
+        const fetch = vi.fn().mockResolvedValue({
+          ok: true,
+          json: async () => installation,
+        });
+        const client = makeClient(fetch);
+
+        await expect(client[method]("inst-1")).resolves.toEqual(installation);
+
+        expect(fetch).toHaveBeenCalledWith(
+          expect.objectContaining({
+            method: "post",
+            path: `/api/environments/123/mcp_server_installations/inst-1/${action}/`,
+          }),
+        );
+      },
+    );
+
+    it("surfaces the backend detail message on failure", async () => {
+      const fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: "Forbidden",
+        json: async () => ({ detail: "Only admins can share installations." }),
+      });
+      const client = makeClient(fetch);
+
+      await expect(client.shareMcpInstallation("inst-1")).rejects.toThrow(
+        "Only admins can share installations.",
+      );
+    });
+
+    it("falls back to statusText when the error body is not JSON", async () => {
+      const fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: "Bad Gateway",
+        json: async () => {
+          throw new Error("not json");
+        },
+      });
+      const client = makeClient(fetch);
+
+      await expect(client.unshareMcpInstallation("inst-1")).rejects.toThrow(
+        "Failed to unshare MCP server: Bad Gateway",
+      );
+    });
+  });
+
   describe("getSignalReport", () => {
     function makeClient(fetch: ReturnType<typeof vi.fn>) {
       const client = new PostHogAPIClient(

packages/api-client/src/posthog-client.ts

@@ -169,6 +169,7 @@ import type {
   McpApprovalState,
   McpAuthType,
   McpCategory,
+  McpInstallationScope,
   McpInstallationTool,
   McpRecommendedServer,
   McpServerInstallation,
@@ -177,6 +178,7 @@ export type {
   McpApprovalState,
   McpAuthType,
   McpCategory,
+  McpInstallationScope,
   McpInstallationTool,
   McpRecommendedServer,
   McpServerInstallation,
@@ -3959,6 +3961,7 @@ export class PostHogAPIClient {
     client_secret?: string;
     install_source?: "posthog" | "posthog-code";
     posthog_code_callback_url?: string;
+    scope?: "personal" | "shared";
   }): Promise<McpServerInstallation | Schemas.OAuthRedirectResponse> {
     const teamId = await this.getTeamId();
     const apiUrl = new URL(
@@ -4039,6 +4042,7 @@ export class PostHogAPIClient {
     api_key?: string;
     install_source?: "posthog" | "posthog-code";
     posthog_code_callback_url?: string;
+    scope?: "personal" | "shared";
   }): Promise<McpServerInstallation | Schemas.OAuthRedirectResponse> {
     const teamId = await this.getTeamId();
     const path = `/api/environments/${teamId}/mcp_server_installations/install_template/`;
@@ -4062,6 +4066,43 @@ export class PostHogAPIClient {
       | Schemas.OAuthRedirectResponse;
   }
 
+  /** Escalate a personal installation to team-wide shared (owner + admin only). */
+  async shareMcpInstallation(
+    installationId: string,
+  ): Promise<McpServerInstallation> {
+    return this.postMcpInstallationScopeAction(installationId, "share");
+  }
+
+  /** Revert a shared installation to personal (owner or admin). */
+  async unshareMcpInstallation(
+    installationId: string,
+  ): Promise<McpServerInstallation> {
+    return this.postMcpInstallationScopeAction(installationId, "unshare");
+  }
+
+  private async postMcpInstallationScopeAction(
+    installationId: string,
+    action: "share" | "unshare",
+  ): Promise<McpServerInstallation> {
+    const teamId = await this.getTeamId();
+    const path = `/api/environments/${teamId}/mcp_server_installations/${installationId}/${action}/`;
+    const response = await this.api.fetcher.fetch({
+      method: "post",
+      url: new URL(`${this.api.baseUrl}${path}`),
+      path,
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new Error(
+        (errorData as { detail?: string }).detail ??
+          `Failed to ${action} MCP server: ${response.statusText}`,
+      );
+    }
+
+    return (await response.json()) as McpServerInstallation;
+  }
+
   async authorizeMcpInstallation(options: {
     installation_id: string;
     install_source?: "posthog" | "posthog-code";

packages/api-client/src/types.ts

@@ -5,6 +5,7 @@ export type McpCategory = Schemas.CategoryEnum;
 export type McpApprovalState =
   Schemas.MCPServerInstallationToolApprovalStateEnum;
 export type McpAuthType = Schemas.MCPAuthTypeEnum;
+export type McpInstallationScope = Schemas.MCPServerInstallationScopeEnum;
 export type McpRecommendedServer = Schemas.MCPServerTemplate;
 export type McpServerInstallation = Schemas.MCPServerInstallation;
 export type McpInstallationTool = Schemas.MCPServerInstallationTool;

packages/core/src/mcp-servers/customServerForm.test.ts

@@ -17,6 +17,7 @@ function values(
     apiKey: "",
     clientId: "",
     clientSecret: "",
+    scope: "personal",
     ...overrides,
   };
 }
@@ -75,6 +76,10 @@ describe("buildCustomServerRequest", () => {
     ).toBeUndefined();
   });
 
+  it.each(["personal", "shared"] as const)("forwards the %s scope", (scope) => {
+    expect(buildCustomServerRequest(values({ scope })).scope).toBe(scope);
+  });
+
   it("includes client_id/client_secret only for oauth when non-empty", () => {
     const req = buildCustomServerRequest(
       values({ authType: "oauth", clientId: " cid ", clientSecret: " sec " }),

packages/core/src/mcp-servers/customServerForm.ts

@@ -1,4 +1,7 @@
-import type { McpAuthType } from "@posthog/api-client/types";
+import type {
+  McpAuthType,
+  McpInstallationScope,
+} from "@posthog/api-client/types";
 
 export interface CustomServerFormValues {
   name: string;
@@ -8,6 +11,7 @@ export interface CustomServerFormValues {
   apiKey: string;
   clientId: string;
   clientSecret: string;
+  scope: McpInstallationScope;
 }
 
 export interface CustomServerRequest {
@@ -18,6 +22,7 @@ export interface CustomServerRequest {
   api_key?: string;
   client_id?: string;
   client_secret?: string;
+  scope: McpInstallationScope;
 }
 
 export function isValidMcpUrl(url: string): boolean {
@@ -38,6 +43,7 @@ export function buildCustomServerRequest(
     url: values.url.trim(),
     description: values.description.trim(),
     auth_type: values.authType,
+    scope: values.scope,
     ...(values.authType === "api_key" && values.apiKey
       ? { api_key: values.apiKey }
       : {}),

packages/core/src/mcp-servers/installFlow.test.ts

@@ -33,11 +33,13 @@ describe("installTemplateWithOAuth", () => {
     const result = await installTemplateWithOAuth(client, oauth, {
       template_id: "tpl-1",
       api_key: "k",
+      scope: "shared",
     });
 
     expect(client.installMcpTemplate).toHaveBeenCalledWith({
       template_id: "tpl-1",
       api_key: "k",
+      scope: "shared",
       install_source: "posthog-code",
       posthog_code_callback_url: "cb://here",
     });
@@ -82,13 +84,15 @@ describe("installCustomWithOAuth", () => {
       url: "https://x",
       description: "d",
       auth_type: "oauth",
+      scope: "shared",
     });
 
     expect(client.installCustomMcpServer).toHaveBeenCalledWith({
       name: "N",
       url: "https://x",
       description: "d",
       auth_type: "oauth",
+      scope: "shared",
       install_source: "posthog-code",
       posthog_code_callback_url: "cb://here",
     });

packages/core/src/mcp-servers/installFlow.ts

@@ -1,5 +1,6 @@
 import type {
   McpAuthType,
+  McpInstallationScope,
   McpServerInstallation,
 } from "@posthog/api-client/types";
 
@@ -15,6 +16,7 @@ export interface InstallFlowClient {
     api_key?: string;
     install_source?: "posthog" | "posthog-code";
     posthog_code_callback_url?: string;
+    scope?: McpInstallationScope;
   }): Promise<InstallResult>;
   installCustomMcpServer(options: {
     name: string;
@@ -26,6 +28,7 @@ export interface InstallFlowClient {
     client_secret?: string;
     install_source?: "posthog" | "posthog-code";
     posthog_code_callback_url?: string;
+    scope?: McpInstallationScope;
   }): Promise<InstallResult>;
   authorizeMcpInstallation(options: {
     installation_id: string;
@@ -55,7 +58,11 @@ function hasRedirect(data: InstallResult): data is OAuthRedirect {
 export async function installTemplateWithOAuth(
   client: InstallFlowClient,
   oauth: IOAuthCallback,
-  vars: { template_id: string; api_key?: string },
+  vars: {
+    template_id: string;
+    api_key?: string;
+    scope?: McpInstallationScope;
+  },
 ): Promise<OAuthCallbackResult> {
   const { callbackUrl } = await oauth.getCallbackUrl();
   const data = await client.installMcpTemplate({
@@ -80,6 +87,7 @@ export async function installCustomWithOAuth(
     api_key?: string;
     client_id?: string;
     client_secret?: string;
+    scope?: McpInstallationScope;
   },
 ): Promise<OAuthCallbackResult> {
   const { callbackUrl } = await oauth.getCallbackUrl();

packages/core/src/mcp-servers/status.test.ts

@@ -16,6 +16,7 @@ function makeInstallation(
     updated_at: "2026-01-01T00:00:00Z",
     needs_reauth: false,
     pending_oauth: false,
+    scope: "personal",
     ...overrides,
   };
 }