feat(mcp): PostHog MCP analytics for the Terminal49 MCP server

.env.local.example

@@ -15,3 +15,7 @@ T49_API_BASE_URL=http://localhost:3000/v2
 # --- Optional hardening / observability ---
 # T49_MCP_ALLOWED_HOSTS=localhost:4000
 # SENTRY_ENABLED=false
+# PostHog tool analytics stays off locally unless you set a project key.
+# POSTHOG_PROJECT_API_KEY=phc_...
+# POSTHOG_HOST=https://f.terminal49.com
+# POSTHOG_DEBUG=true

.env.sample

@@ -19,3 +19,11 @@ SENTRY_TRACES_SAMPLE_RATE=1.0
 SENTRY_MCP_RECORD_INPUTS=false
 SENTRY_MCP_RECORD_OUTPUTS=false
 SENTRY_SEND_DEFAULT_PII=false
+
+# PostHog MCP Analytics (optional)
+# Leave POSTHOG_PROJECT_API_KEY unset to disable: no client, no network call.
+# Tool arguments and response bodies are never captured.
+POSTHOG_ENABLED=true
+POSTHOG_PROJECT_API_KEY=
+# POSTHOG_HOST=https://f.terminal49.com
+# POSTHOG_DEBUG=false

api/mcp.ts

@@ -12,6 +12,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import * as Sentry from '@sentry/node';
 import { createTerminal49McpServer } from '../packages/mcp/src/server.js';
+import { flushPostHogEvents } from '../packages/mcp/src/posthog.js';
 import { captureMcpException } from '../packages/mcp/src/sentry.js';
 import { protectedResourceMetadataUrl } from '../packages/mcp/src/resource.js';
 
@@ -24,7 +25,7 @@
 type ResponseLike = {
  headersSent: boolean;
  status(code: number): ResponseLike;
  json(payload: unknown): void;
  setHeader(name: string, value: string): void;
  end(): void;
  on(event: 'close' | 'finish', listener: () => void): void;
@@ -62,12 +63,12 @@
  if (token.length > 0) {
  const scheme =
  authMatch[1].toLowerCase() === 'bearer' ? 'Bearer' : 'Token';
  return { scheme, token, source: 'authorization' };
  }
  }
  }
 
  return {};
 }
 
 type ResolvedTerminal49Auth = {
@@ -177,14 +178,14 @@
  });
  } catch (error) {
  throw new ConnectedClientResolveError(
  `Terminal49 connected client resolve request failed: ${(error as Error).message}`,
  'upstream',
  );
  }
 
  let payload: ConnectedClientResolutionResponse = {};
  try {
  payload = (await response.json()) as ConnectedClientResolutionResponse;
  } catch {
  payload = {};
  }
@@ -243,7 +244,7 @@
 function logLifecycle(
  event: string,
  requestId: string,
  details: Record<string, unknown> = {},
 ): void {
  console.error(
  JSON.stringify({
@@ -405,7 +406,7 @@
  try {
  await transport.close();
  } catch (error) {
  const err = error as Error;
  cleanupErrors.push(`transport.close: ${err.message}`);
  }
  }
@@ -604,5 +605,12 @@
  if (shouldFlushSentry || Sentry.isInitialized()) {
  await Sentry.flush(2000).catch(() => undefined);
  }
+ // Vercel freezes the function the moment the response is sent, so any batch
+ // still queued in the PostHog client would be dropped (or leak into the next
+ // invocation on a reused instance). Awaiting the flush here mirrors the
+ // Sentry.flush() above: one batched request per invocation. Deliberately
+ // preferred over `waitUntil`, which would add a @vercel/functions
+ // dependency for the same guarantee. No-ops when PostHog is unconfigured.
+ await flushPostHogEvents();
  }
 }

packages/mcp/.env.example

@@ -18,6 +18,17 @@ SENTRY_MCP_RECORD_INPUTS=false
 SENTRY_MCP_RECORD_OUTPUTS=false
 SENTRY_SEND_DEFAULT_PII=false
 
+# PostHog MCP Analytics (optional)
+# Tool-usage analytics via @posthog/mcp. Leave POSTHOG_PROJECT_API_KEY unset to
+# disable: no client is constructed and no network call is made.
+# Tool arguments and response bodies are never captured (they carry customer
+# container/shipment identifiers) — see packages/mcp/src/posthog.ts.
+POSTHOG_ENABLED=true
+POSTHOG_PROJECT_API_KEY=
+# Defaults to the first-party proxy used by the docs site (docs/docs.json).
+# POSTHOG_HOST=https://f.terminal49.com
+# POSTHOG_DEBUG=false
+
 # Vercel Configuration (optional, auto-detected)
 VERCEL=1
 VERCEL_URL=your-deployment.vercel.app

packages/mcp/WORKOS_MCP_SETUP.md

@@ -54,6 +54,10 @@ In the WorkOS environment referenced by `WORKOS_AUTHORIZATION_SERVER_URL`:
 | `T49_CONNECTED_CLIENTS_RESOLVE_SECRET` | the resolve shared secret | Required to call `/connected-clients/resolve` |
 | `T49_MCP_ALLOWED_HOSTS` | include `mcp.terminal49.com` (if set at all) | Host allowlist; missing host → 403 |
 | `T49_MCP_SCOPES_SUPPORTED` | **leave unset** | WorkOS only issues `openid/profile/email/offline_access`; advertising `mcp:tools` etc. causes `invalid_scope` |
+| `POSTHOG_PROJECT_API_KEY` | the PostHog project API key | Enables MCP tool-usage analytics. **Leave unset and the integration is inert** — no client, no network call |
+| `POSTHOG_HOST` | optional; defaults to `https://f.terminal49.com` | First-party ingestion proxy, same host the docs site uses (`docs/docs.json`) |
+| `POSTHOG_ENABLED` | optional; defaults to `true` | Set `false` to kill-switch analytics without removing the key |
+| `POSTHOG_DEBUG` | optional; defaults to `false` | Verbose PostHog client logging; leave off in production |
 
 ## 3. Smoke tests
 

packages/mcp/package.json

@@ -26,8 +26,10 @@
  },
  "dependencies": {
  "@modelcontextprotocol/sdk": "^1.29.0",
+ "@posthog/mcp": "0.10.1",
  "@sentry/node": "^10.55.0",
  "@terminal49/sdk": "0.3.1",
+ "posthog-node": "^5.0.0",
  "zod": "~4.3.6"
  },
  "devDependencies": {

packages/mcp/src/instrument.ts

@@ -1,3 +1,5 @@
+import { initializePostHogFromEnv } from './posthog.js';
 import { initializeSentryFromEnv } from './sentry.js';
 
 initializeSentryFromEnv();
+initializePostHogFromEnv();