PostHog MCP Server: Analytics, Feature Flags, Error Tracking

Overview

The PostHog MCP (Model Context Protocol) server is a lightweight telemetry gateway that centralizes analytics events, feature flag evaluation, and error tracking into a single service. Instead of wiring each application to separate systems, MCP accepts context-rich payloads (events, errors, flag evaluation requests), normalizes them, and routes them to downstream storage, evaluation engines, or external integrations. This reduces duplicated instrumentation and gives engineering teams one place to control telemetry behavior.

MCP is useful when you need consistent metrics and behavior across services, fast feature-flag evaluation close to clients, and unified crash/error visibility tied to user and session context. It is designed to be deployed alongside your stack (containers or Kubernetes) and to integrate with common components such as Postgres, Redis, Kafka, S3, and observability tools.

Features

• Unified ingestion API for analytics events, error reports, and context blobs
• Server-side and client-side feature flag evaluation APIs
• Error aggregation with contextual metadata (user, session, breadcrumbs)
• Pluggable persistence and export integrations (Postgres, Kafka, S3, etc.)
• Low-latency flag evaluation with caching (Redis) and local evaluation support
• Webhooks and plugin pipeline for transforming and forwarding events
• Health and metrics endpoints for monitoring
• Open APIs / SDK-friendly endpoints for quick integration

Installation / Configuration

Quick start with Docker Compose (example includes Postgres and Redis):

# docker-compose.yml
version: "3.8"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: mcp
      POSTGRES_PASSWORD: mcp
      POSTGRES_DB: mcp
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7
    command: ["redis-server", "--save", "60", "1"]

  mcp:
    image: ghcr.io/posthog/mcp:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://mcp:mcp@postgres:5432/mcp
      REDIS_URL: redis://redis:6379
      PORT: "8080"
      LOG_LEVEL: info
    depends_on:
      - postgres
      - redis

volumes:
  pgdata:

Run locally:

# start services
docker compose up -d

# view logs
docker compose logs -f mcp

Environment variables commonly used:

• DATABASE_URL — Postgres connection string
• REDIS_URL — Redis connection string for caching and locking
• PORT — HTTP port for MCP
• LOG_LEVEL — debug|info|warn|error
• PLUGINS_CONFIG — JSON/YAML config path for plugin pipeline
• EXTERNAL_INTEGRATIONS_* — credentials for Kafka, S3, etc.

If you prefer building from source:

git clone https://github.com/posthog/mcp.git
cd mcp
# build (example assumes Go toolchain)
go build ./cmd/mcp
./mcp --config config.yml

Adjust service configuration to match your infrastructure (Kubernetes manifests, Helm charts, or systemd units).

Available Tools / Resources

Common HTTP endpoints (names are representative; check the service OpenAPI for exact routes):

Developer resources:

• GitHub repository: https://github.com/posthog/mcp
• Example configs and integrations: look in the repo’s examples/ or docs/ folders
• OpenAPI/Swagger spec (if present in repo) for exact API contracts
• Postgres schema migrations and plugin config examples bundled in the repo

Use Cases

1. Track a page view (analytics ingestion)

curl -X POST "http://localhost:8080/api/collect" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "pageview",
    "timestamp": "2026-04-01T12:34:56Z",
    "distinct_id": "user_123",
    "properties": {"path": "/pricing", "title": "Pricing"}
  }'

MCP will validate and persist the event, and optionally forward it to downstream storage or analytics processors.

2. Evaluate a feature flag for a request

curl -X POST "http://localhost:8080/api/flags/evaluate" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_key": "new-payment-flow",
    "identity": {"distinct_id": "user_123", "properties": {"plan": "pro"}}
  }'

The server responds with a boolean or polymorphic flag value and the rationale (matching rule, rollout percentage). Use this synchronously in backend request handling to decide behavior.

3. Send an error with context for aggregation

curl -X POST "http://localhost:8080/api/errors" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "TypeError: x is not a function",
    "stack": "...stack trace...",
    "timestamp": "2026-04-01T12:40:00Z",
    "distinct_id": "user_123",
    "metadata": {"route": "/checkout", "release": "v1.4.0"}
  }'

MCP attaches user/session context and groups similar errors; plugins can forward grouped issues to alerting channels.

Notes and Next Steps

• Consult the