mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 02:00:52 +01:00
Dotta
d387cc0ff0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Connection intents need secure provider implementations to complete setup. > - Some providers use managed OAuth or external credential brokers. > - Those tokens must stay out of durable Paperclip state and fail closed when refresh fails. > - This pull request adds managed connector backends and the required storage contract. > - The benefit is safer provider setup with governed credential lifecycles. ## Linked Issues or Issue Description Refs #11965 This is stack 8 of 11. It depends on stack 7 and replaces another reviewable part of #11965. ## What Changed - Add managed Google Workspace and external connector backends. - Add Vercel Connect support without storing provider bearer tokens. - Add replay-safe migration 0232 and its generated snapshot. - Fail closed and clear stale token bindings when organization OAuth refresh needs reauthorization. ## Verification - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/tool-access-service.test.ts` - Result: 194 tests passed. - `pnpm --filter @paperclipai/db check:migrations` - `pnpm build` - `pnpm exec vitest run --project @paperclipai/server server/src/services/remote-url-credentials.test.ts` (5 passed, including URL userinfo vault extraction) ## Risks - Broker metadata errors can block provider setup. - OAuth refresh failure disables the shared organization connection until reauthorization. - Migration 0232 is generated, ordered after 0231, and safe to replay. > I checked `ROADMAP.md`. This stack continues the existing app connection work from #11965 and does not duplicate another planned item. ## Model Used OpenAI Codex, GPT-5. The runtime model ID and context window were not exposed. The model used reasoning, tool use, and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have linked the public source pull request with `Refs #` - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
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. Known writes and destructive actions default to
|
|
**Ask first**, and unknown PostHog tools default to write risk so they inherit
|
|
that approval gate unless the operator changes the selection.
|
|
|
|
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.
|