PostHog connector

import { posthog } from '@noir-agent/agent/connectors/posthog'

connectors: {
  posthog: posthog({
    apiKey: process.env.POSTHOG_PERSONAL_API_KEY!,
    organizationId: process.env.POSTHOG_ORGANIZATION_ID,
    projectId: process.env.POSTHOG_PROJECT_ID,
    readonly: true,
    features: ['data_schema', 'insights', 'sql'],
  }),
}

The connector uses https://mcp.posthog.com/mcp in CLI mode and exposes one compact posthog.exec surface. The model can search, inspect, and call the configured PostHog tools without placing the full remote catalog in every prompt.

Authentication

Use a PostHog personal API key. The default lookup is POSTHOG_PERSONAL_API_KEY, then POSTHOG_API_KEY. Set organization and project IDs to prevent ambiguity when the key can access multiple projects.

Read-only default

readonly defaults to true. Noir sets PostHog's read-only query parameter and header. In read-only mode the tool effect is read, approval is never, and retry is safe. If you explicitly enable writes, the tool becomes a write with requester approval and no automatic retry.

Catalog filtering

features and tools are optional allowlists encoded into the MCP URL. Entries may contain letters, numbers, hyphens, and underscores. Narrowing the surface improves model selection and reduces accidental access.

Prompting for reliable analysis

Require the agent to identify event/property definitions, state filters and timezones, explain comparison windows, and separate measurement from interpretation. PostHog output can contain user-generated strings, so treat it as data rather than executable instruction.

Health and errors

The connector inherits MCP ping health. Authentication, schema, and tool errors are returned as tool failures rather than invented data. Retry transient transport failures, but do not silently broaden project or tool access when a call is forbidden.