paperclip/doc/connections/POSTHOG.md

PostHog connection

Paperclip connects to PostHog's hosted MCP service at https://mcp.posthog.com/mcp. The connection supports two explicit methods:

• browser OAuth, which is recommended for hosted PostHog accounts; or
• a PostHog personal API key stored as a Paperclip secret and sent as an Authorization: Bearer ... header.

The retained Vercel Connect implementation can reference a connector managed in Vercel without storing a PostHog bearer. That preview's new-connection UI is currently withheld; the supported product path remains PostHog OAuth or an API key managed directly by Paperclip.

Paperclip does not silently fall back from OAuth to an API key. The selected method is saved on the connection and reused for reconnects.

This curated connection is the polished route and is what most users should use: it provides branding and optional project/read-only/feature/tool controls, field validation, and tailored guidance. None of it is required to reach PostHog's MCP server. Since PAP-17087, PostHog can also be connected generically from Connect your own MCP server by pasting https://mcp.posthog.com/mcp — with a personal API key, with explicit headers, or through browser sign-in — with no Paperclip-specific code involved. See Connecting any remote MCP server.

Service involvement

PostHog hosts both the MCP resource and OAuth authorization service. Paperclip discovers the OAuth endpoints, dynamically registers the client when needed, stores returned credentials as secret references, and handles the callback at /api/tools/oauth/callback. No Paperclip-operated vendor relay is involved.

sequenceDiagram
    actor A as Administrator
    participant P as Paperclip
    participant M as mcp.posthog.com
    participant O as oauth.posthog.com

    A->>P: Choose PostHog sign-in
    P->>M: Discover protected-resource metadata
    M-->>P: Authorization server metadata URL
    P->>O: Discover endpoints and register OAuth client
    O-->>P: Client registration
    P-->>A: Open browser authorization
    A->>O: Approve access
    O-->>P: Redirect to /api/tools/oauth/callback
    P->>O: Exchange authorization code
    O-->>P: Access and refresh tokens
    P->>M: tools/list with optional project and catalog controls
    M-->>P: PostHog tool catalog

The current hosted endpoints are:

Purpose	Endpoint
MCP resource	https://mcp.posthog.com/mcp
Protected-resource metadata	https://mcp.posthog.com/.well-known/oauth-protected-resource/mcp
Authorization-server metadata	https://oauth.posthog.com/.well-known/oauth-authorization-server
Authorize	https://oauth.posthog.com/oauth/authorize/
Token	https://oauth.posthog.com/oauth/token/
Dynamic client registration	https://oauth.posthog.com/oauth/register/
Revoke	https://oauth.posthog.com/oauth/revoke/
Paperclip callback	/api/tools/oauth/callback

Redirect-URI constraints and token lifetimes remain provider-controlled and must be rechecked during credentialed QA; Paperclip does not encode guessed values for either.

Administrator setup

1. In Apps → Browse, choose PostHog.
2. Explicitly choose Sign in with PostHog or Use a personal API key.
3. Continue directly with PostHog's defaults. No project ID is required.
4. Open Advanced only when you need to pin the connection to a numeric project ID, force Read-only mode, use a customer-owned OAuth app, or narrow the catalog with Feature groups or Individual tools.
5. The default setup requests all feature groups and tools. Paperclip fixes the advanced response mode to individual tools so each action can be governed; CLI mode is unavailable until nested execution is governed.
6. For OAuth, continue through browser consent. For API-key setup, create a personal API key using PostHog's MCP Server preset and paste it into Paperclip. Never put the key in connection configuration or a URL.
7. Review discovered actions. Every discovered action starts Allowed, including writes and destructive actions. Unknown PostHog tools are still classified as write risk so operators can identify and narrow them when needed.

When configured, Paperclip sends the optional project pin as the x-posthog-project-id managed header. Without it, PostHog keeps an active project and exposes its project-switching tool. Pinning removes that switching capability. Paperclip sends configured readonly, features, tools, and internally managed mode values as query parameters. Leaving the optional feature and tool filters blank exposes the full catalog. The managed header is identical during catalog discovery and tool execution, and a caller cannot override it. PostHog documents these options in its MCP overview and MCP FAQ.

PostHog does not charge for MCP requests themselves, but the actions they perform can consume normal PostHog usage or AI credits.