3.5 KiB
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.
Paperclip does not silently fall back from OAuth to an API key. The selected method is saved on the connection and reused for reconnects.
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 and project filters
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 project and safety filters
M-->>P: Filtered 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
- In Apps → Browse, choose PostHog.
- Explicitly choose Sign in with PostHog or Use a personal API key.
- Enter the numeric PostHog project ID.
- Keep Read-only mode enabled unless agents have an approved need to make changes.
- Limit the catalog with one or both of Feature groups and Individual tools. Paperclip currently fixes response mode to individual tools; CLI mode is unavailable until nested execution is governed.
- 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.
- Review discovered actions. Known writes ask first, destructive or nested execution tools remain quarantined, and unknown PostHog tools default to write risk until reviewed.
The safe configuration is projected to PostHog as project_id, readonly,
features, tools, and mode query parameters. 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.