104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# 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](./VERCEL-CONNECT.md) 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](/PAP/issues/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](./GENERIC-REMOTE-MCP.md).
|
|
|
|
## 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.
|
|
|
|
```mermaid
|
|
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](https://posthog.com/docs/model-context-protocol) and [MCP
|
|
FAQ](https://posthog.com/docs/model-context-protocol/faq).
|
|
|
|
PostHog does not charge for MCP requests themselves, but the actions they
|
|
perform can consume normal PostHog usage or AI credits.
|