feat: add region param and OAuth option for MCP setup (#220)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: MattBro

src/mcp.ts

@@ -4,11 +4,7 @@ import {
   removeMCPServerFromClientsStep,
 } from './steps/add-mcp-server-to-clients';
 import clack from './utils/clack';
-import { abort } from './utils/clack-utils';
 import type { CloudRegion } from './utils/types';
-import opn from 'opn';
-import { getCloudUrlFromRegion } from './utils/urls';
-import { sleep } from './lib/helper-functions';
 import { enableDebugLogs } from './utils/debug';
 
 export const runMCPInstall = async (options: {
@@ -38,6 +34,10 @@ export const runMCPInstall = async (options: {
     )}`,
   );
 
+  clack.log.message(
+    `You'll be prompted to log in to PostHog when you first use the MCP.`,
+  );
+
   clack.log.message(`Get started with some prompts like:
 - What feature flags do I have active?
 - Add a new feature flag for our homepage redesign
@@ -66,46 +66,3 @@ export const runMCPRemove = async (options?: { local?: boolean }) => {
     )}`,
   );
 };
-
-export const getPersonalApiKey = async (options: {
-  cloudRegion: CloudRegion;
-}): Promise<string> => {
-  const cloudUrl = getCloudUrlFromRegion(options.cloudRegion);
-
-  const urlToOpen = `${cloudUrl}/settings/user-api-keys?preset=mcp_server`;
-
-  const spinner = clack.spinner();
-  spinner.start(
-    `Opening your project settings so you can get a Personal API key...`,
-  );
-
-  await sleep(1500);
-
-  spinner.stop(
-    `Opened your project settings. If the link didn't open automatically, open the following URL in your browser to get a Personal API key: \n\n${chalk.cyan(
-      urlToOpen,
-    )}`,
-  );
-
-  opn(urlToOpen, { wait: false }).catch(() => {
-    // opn throws in environments that don't have a browser (e.g. remote shells) so we just noop here
-  });
-
-  const personalApiKey = await clack.password({
-    message: 'Paste in your Personal API key:',
-    validate(value) {
-      if (value.length === 0) return `Value is required!`;
-
-      if (!value.startsWith('phx_')) {
-        return `That doesn't look right, are you sure you copied the right key? It should start with 'phx_'`;
-      }
-    },
-  });
-
-  if (!personalApiKey) {
-    await abort('Unable to proceed without a personal API key.');
-    return '';
-  }
-
-  return personalApiKey as string;
-};

src/steps/add-mcp-server-to-clients/MCPClient.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as jsonc from 'jsonc-parser';
 import { getDefaultServerConfig } from './defaults';
+import type { CloudRegion } from '../../utils/types';
 
 export type MCPServerConfig = Record<string, unknown>;
 
@@ -11,9 +12,10 @@ export abstract class MCPClient {
   abstract getServerPropertyName(): string;
   abstract isServerInstalled(local?: boolean): Promise<boolean>;
   abstract addServer(
-    apiKey: string,
+    apiKey?: string,
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): Promise<{ success: boolean }>;
   abstract removeServer(local?: boolean): Promise<{ success: boolean }>;
   abstract isClientSupported(): Promise<boolean>;
@@ -31,12 +33,19 @@ export abstract class DefaultMCPClient extends MCPClient {
   }
 
   getServerConfig(
-    apiKey: string,
+    apiKey: string | undefined,
     type: 'sse' | 'streamable-http',
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): MCPServerConfig {
-    return getDefaultServerConfig(apiKey, type, selectedFeatures, local);
+    return getDefaultServerConfig(
+      apiKey,
+      type,
+      selectedFeatures,
+      local,
+      region,
+    );
   }
 
   async isServerInstalled(local?: boolean): Promise<boolean> {
@@ -61,18 +70,20 @@ export abstract class DefaultMCPClient extends MCPClient {
   }
 
   async addServer(
-    apiKey: string,
+    apiKey?: string,
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): Promise<{ success: boolean }> {
-    return this._addServerType(apiKey, 'sse', selectedFeatures, local);
+    return this._addServerType(apiKey, 'sse', selectedFeatures, local, region);
   }
 
   async _addServerType(
-    apiKey: string,
+    apiKey: string | undefined,
     type: 'sse' | 'streamable-http',
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): Promise<{ success: boolean }> {
     try {
       const configPath = await this.getConfigPath();
@@ -94,6 +105,7 @@ export abstract class DefaultMCPClient extends MCPClient {
         type,
         selectedFeatures,
         local,
+        region,
       );
       const typedConfig = existingConfig as Record<string, any>;
       if (!typedConfig[serverPropertyName]) {

src/steps/add-mcp-server-to-clients/__tests__/defaults.test.ts

@@ -0,0 +1,126 @@
+import {
+  buildMCPUrl,
+  getDefaultServerConfig,
+  getNativeHTTPServerConfig,
+} from '../defaults';
+
+describe('defaults', () => {
+  describe('buildMCPUrl', () => {
+    it('should build base URL for streamable-http type', () => {
+      const url = buildMCPUrl('streamable-http');
+      expect(url).toBe('https://mcp.posthog.com/mcp');
+    });
+
+    it('should build base URL for sse type', () => {
+      const url = buildMCPUrl('sse');
+      expect(url).toBe('https://mcp.posthog.com/sse');
+    });
+
+    it('should use localhost for local mode', () => {
+      const url = buildMCPUrl('streamable-http', undefined, true);
+      expect(url).toBe('http://localhost:8787/mcp');
+    });
+
+    it('should add features param when not all features selected', () => {
+      const url = buildMCPUrl('streamable-http', ['dashboards', 'insights']);
+      expect(url).toBe(
+        'https://mcp.posthog.com/mcp?features=dashboards,insights',
+      );
+    });
+
+    it('should add region param for EU region', () => {
+      const url = buildMCPUrl('streamable-http', undefined, false, 'eu');
+      expect(url).toBe('https://mcp.posthog.com/mcp?region=eu');
+    });
+
+    it('should not add region param for US region (default)', () => {
+      const url = buildMCPUrl('streamable-http', undefined, false, 'us');
+      expect(url).toBe('https://mcp.posthog.com/mcp');
+    });
+
+    it('should not add region param in local mode', () => {
+      const url = buildMCPUrl('streamable-http', undefined, true, 'eu');
+      expect(url).toBe('http://localhost:8787/mcp');
+    });
+
+    it('should combine features and region params', () => {
+      const url = buildMCPUrl('streamable-http', ['dashboards'], false, 'eu');
+      expect(url).toBe(
+        'https://mcp.posthog.com/mcp?features=dashboards&region=eu',
+      );
+    });
+  });
+
+  describe('getDefaultServerConfig', () => {
+    it('should return config with auth header when API key provided', () => {
+      const config = getDefaultServerConfig('phx_test123', 'sse');
+      expect(config).toEqual({
+        command: 'npx',
+        args: [
+          '-y',
+          'mcp-remote@latest',
+          'https://mcp.posthog.com/sse',
+          '--header',
+          'Authorization:${POSTHOG_AUTH_HEADER}',
+        ],
+        env: {
+          POSTHOG_AUTH_HEADER: 'Bearer phx_test123',
+        },
+      });
+    });
+
+    it('should return config without auth header for OAuth mode (no API key)', () => {
+      const config = getDefaultServerConfig(undefined, 'sse');
+      expect(config).toEqual({
+        command: 'npx',
+        args: ['-y', 'mcp-remote@latest', 'https://mcp.posthog.com/sse'],
+      });
+      expect(config).not.toHaveProperty('env');
+    });
+
+    it('should include region in URL for EU users in OAuth mode', () => {
+      const config = getDefaultServerConfig(
+        undefined,
+        'streamable-http',
+        undefined,
+        false,
+        'eu',
+      );
+      expect(config.args).toContain('https://mcp.posthog.com/mcp?region=eu');
+    });
+  });
+
+  describe('getNativeHTTPServerConfig', () => {
+    it('should return config with headers when API key provided', () => {
+      const config = getNativeHTTPServerConfig(
+        'phx_test123',
+        'streamable-http',
+      );
+      expect(config).toEqual({
+        url: 'https://mcp.posthog.com/mcp',
+        headers: {
+          Authorization: 'Bearer phx_test123',
+        },
+      });
+    });
+
+    it('should return config without headers for OAuth mode (no API key)', () => {
+      const config = getNativeHTTPServerConfig(undefined, 'streamable-http');
+      expect(config).toEqual({
+        url: 'https://mcp.posthog.com/mcp',
+      });
+      expect(config).not.toHaveProperty('headers');
+    });
+
+    it('should include region in URL for EU users', () => {
+      const config = getNativeHTTPServerConfig(
+        undefined,
+        'streamable-http',
+        undefined,
+        false,
+        'eu',
+      );
+      expect(config.url).toBe('https://mcp.posthog.com/mcp?region=eu');
+    });
+  });
+});

src/steps/add-mcp-server-to-clients/clients/__tests__/claude.test.ts

@@ -329,6 +329,35 @@ describe('ClaudeMCPClient', () => {
         'sse',
         undefined,
         undefined,
+        undefined,
+      );
+    });
+
+    it('should call getDefaultServerConfig with undefined API key for OAuth mode', async () => {
+      existsSyncMock.mockReturnValue(false);
+
+      await client.addServer(undefined);
+
+      expect(getDefaultServerConfigMock).toHaveBeenCalledWith(
+        undefined,
+        'sse',
+        undefined,
+        undefined,
+        undefined,
+      );
+    });
+
+    it('should pass region parameter to getDefaultServerConfig', async () => {
+      existsSyncMock.mockReturnValue(false);
+
+      await client.addServer(mockApiKey, undefined, undefined, 'eu');
+
+      expect(getDefaultServerConfigMock).toHaveBeenCalledWith(
+        mockApiKey,
+        'sse',
+        undefined,
+        undefined,
+        'eu',
       );
     });
   });

src/steps/add-mcp-server-to-clients/clients/claude-code.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import { execSync } from 'child_process';
 import { analytics } from '../../../utils/analytics';
 import { debug } from '../../../utils/debug';
+import type { CloudRegion } from '../../../utils/types';
 import * as os from 'os';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -111,19 +112,23 @@ export class ClaudeCodeMCPClient extends DefaultMCPClient {
   }
 
   addServer(
-    apiKey: string,
+    apiKey?: string,
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): Promise<{ success: boolean }> {
     const claudeBinary = this.findClaudeBinary();
     if (!claudeBinary) {
       return Promise.resolve({ success: false });
     }
 
     const serverName = local ? 'posthog-local' : 'posthog';
-    const url = buildMCPUrl('streamable-http', selectedFeatures, local);
+    const url = buildMCPUrl('streamable-http', selectedFeatures, local, region);
 
-    const command = `${claudeBinary} mcp add --transport http ${serverName} ${url} --header "Authorization: Bearer ${apiKey}" -s user`;
+    // OAuth mode: no auth header
+    const authArgs = apiKey ? `--header "Authorization: Bearer ${apiKey}"` : '';
+    const command =
+      `${claudeBinary} mcp add --transport http ${serverName} ${url} ${authArgs} -s user`.trim();
 
     try {
       execSync(command);

src/steps/add-mcp-server-to-clients/clients/codex.ts

@@ -3,6 +3,7 @@ import { execSync, spawnSync } from 'node:child_process';
 
 import { DefaultMCPClient } from '../MCPClient';
 import { DefaultMCPClientConfig, getDefaultServerConfig } from '../defaults';
+import type { CloudRegion } from '../../../utils/types';
 
 import { analytics } from '../../../utils/analytics';
 
@@ -60,12 +61,14 @@ export class CodexMCPClient extends DefaultMCPClient {
     apiKey: string,
     selectedFeatures?: string[],
     local?: boolean,
+    region?: CloudRegion,
   ): Promise<{ success: boolean }> {
     const config = getDefaultServerConfig(
       apiKey,
       'sse',
       selectedFeatures,
       local,
+      region,
     );
     const serverName = local ? 'posthog-local' : 'posthog';