paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00

Files

T

39633c2217 docs: connectors catalog, operator-first third revision (#124 )

Connector catalog, setup guides, and shared access documentation,
followed by a final code-accuracy repair pass. This PR does not change
application behavior.

## Final accuracy pass

Checked against shipped Paperclip `v2026.916.0`, commit
`dffc2b3ca1b9e88fa21cb17493083e682dffd1ca`, rather than the dirty local
checkout or the earlier canary baseline.

- Corrects connector/method-specific identity choices, human audiences,
and managed GitHub versus PAT scope and verification.
- Explains that **Always allow** covers different arguments for the same
agent/action/connection, with project scope when present; uses actual
button labels and removes the test-panel control from review
instructions.
- Qualifies new-action quarantine, including safe-default read
exceptions. Removes unconditional approval guarantees.
- Separates provider channel/repository reach from Paperclip sender
authorization.
- Completes sandbox sign-in and model credential-selection instructions
from the current UI implementation.
- Repairs Notion's hub summary, removes incomplete optional
Notion/Sentry client-registration procedures, and corrects Linear's
provider-versus-Paperclip attribution.
- Removes unsupported Postman tier claims, contradictory Cloudinary/Mem0
verification assertions, API-equivalence claims, and overbroad
successful-test assurances.
- Retains Supabase's required project reference: both released method
definitions explicitly require it. An earlier review suggested
otherwise; release code is authoritative here.
- Updates the release baseline and removes draft commit chronology from
the public introduction.

## Availability and remaining runtime gates

- **Google:** Verification is pending. Per the product-owner
clarification, authorization can continue where Google offers an
Advanced option; this is not available for every account and does not
override Workspace policy or other Google prerequisites. Notices on the
hub and all Google guides now distinguish an unverified-app warning from
blocked authorization.
- **Slack is available but not yet fully functional; follow-up fixes are
planned.** For agent tools, the released OAuth endpoint/scope defaults
differ from Slack's documented MCP contract. The page now warns against
treating that route as production-ready and removes the misleading
bot-scope walkthrough. Chat-channel bot setup remains separate.
Engineering must reconcile the integration and run OAuth plus one read
before removing this warning. Source:
https://docs.slack.dev/ai/slack-mcp-server/
- No credentialed connector run was performed in this pass. Code
consistency, provider documentation, UI rendering, and successful live
execution are separate evidence levels. No claim of runtime
certification for all connectors.

## Validation

- Root build: 253 crawlable documentation pages.
- Full `docs:test`: all eight suites passed locally, including
root/subpath routes, sitemap history, fingerprints, navigation, skill
source blocks, crawlable links, doc-link resolution, and SEO metadata.
- Internal-link lint: 258 Markdown files; no broken internal links.
- Latest cleanup: full build, all eight docs:test suites, internal-link
lint and diff whitespace checks passed; 1,878 link-resolution checks.
- Fixed the Calendar MCP reference URL; browser-checked the five
inconclusive external destinations (Miro article loads; Asana, Google
Cloud, OpenAI and xAI reach sign-in/console screens). Authenticated
destinations were not tested beyond those screens.
- Replaced the Sandbox providers editorial TODO with a scope note and
removed the CLI overview's unfinished-guide announcement.
- Browser client navigation: 687 checks passed using installed Chrome.
Initial launch lacked the downloaded Playwright browser; rerun used
`DOCS_CHROMIUM_PATH` without changing the tests.
- Nine representative connector/shared pages at 1440px and 390px: HTTP
200, one article H1, no page-level horizontal overflow. Mobile
screenshot inspected; approval page opened in the Codex browser.
- Navigation audit reports three existing non-connector orphan files;
this patch does not alter those files or their navigation.

The previous revision's provider-page expansion, Google shared setup
guide, navigation additions, and accidental node_modules-symlink cleanup
remain in this PR. Internal review ledgers remain outside the
publication branch. No merge or production deployment authorized.

---------

Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
Co-authored-by: Michael Nguyen <[email protected]>

2026-09-16 22:19:14 -10:00

5.6 KiB

Raw Blame History

seo_title, seo_description

seo_title	seo_description
PostHog Connector	Let agents analyze product usage, errors, and feature flags in PostHog. Project pinning, read-only mode, and why classification is conservative.

PostHog

Agents can query product analytics, investigate errors, and inspect feature flags and experiments in PostHog.

PostHog has a large and fast-moving tool catalog, which shapes how Paperclip handles it: a tool PostHog does not annotate as read-only is classified as a write, and exec is always destructive. That conservative classification is deliberate, and it is explained below.

Before you connect

A PostHog account with access to the project you want agents to use.
Optionally, the project ID you intend to pin to. You can find it in PostHog's project settings.

Connect PostHog

Open Connectors and select PostHog.
On the Access step, choose the identity and which agents may use the connection.
Choose how to authenticate:
- Sign in with PostHog — browser sign-in, the quickest path.
- Use a personal API key — paste a PostHog personal API key.
Optionally set the advanced controls below, then finish.

The defaults work without touching anything else.

Narrow the connection

PostHog offers more scoping controls at setup than most connectors, and they are worth using:

Control	What it does
Pin to project ID	Scopes the connection to one project
Read-only mode	Asks PostHog for a read-only session
Feature groups	Leave blank for every feature group, or list the ones you want
Individual tools	Leave blank for all tools, or name exactly the ones to expose
Tool response mode	How much detail tool responses carry

Note: These are requests Paperclip sends to PostHog, not boundaries Paperclip enforces. The pinned project travels as a request header and the rest as query parameters, so PostHog is what honours them. The effect you will see is a narrower tool list and project scope, and it is worth configuring — but if you need a boundary that does not depend on the provider, use an account or key that cannot reach the other projects in the first place, and set the action permissions.

Pinning to a project is still the most useful setting here. Without it, the connection's reach is every project the authorizing account can see.

For an analysis-only agent, pin the project and turn on read-only mode.

Choose access

Project reach is the PostHog account's, narrowed by the pin you set and honoured by PostHog. On top of that, Paperclip's action settings apply as usual — and those are enforced on Paperclip's side.

Risk classification is deliberately conservative for this provider:

A PostHog tool that PostHog does not explicitly annotate as read-only is classified write, not read. Silently assuming "read" for an unfamiliar tool is the failure worth avoiding when the catalog changes often.
The exec tool is always classified destructive, whatever else it looks like.
Because classification drives the defaults the setup wizard projects into policies, a PostHog connection starts more restrictive than a connector whose provider annotates its tools carefully.

The practical effect is that you will see more tools defaulting to review than on other connectors. That is the intended behaviour, not a misclassification.

Warning: Classification is not a review queue. On a PostHog connection made with your own API key, a tool PostHog adds later becomes active when you Refresh actions — it is governed by the policies already in force, not held back for your approval. Check the list after a refresh. Set action permissions explains which connections do hold new actions back.

Try it

In PostHog, how many pageviews did we get in the last 7 days? Do not create or change anything.

Compare against the same figure in the PostHog UI. A small, bounded query is the right first check — avoid asking for a large unbounded export while you are only proving the connection works.

Note: Illustrative task, not a recorded test result.

Troubleshooting and limitations

Problem	Likely cause	Fix
An agent queried the wrong project	The connection is not pinned	Set Pin to project ID and reconnect if needed
Many tools show as needing approval	Expected — unannotated PostHog tools are classified as writes	Review and set the ones you want to Allowed
A read-looking tool is classified write	PostHog did not annotate it as read-only	Set it to Allowed deliberately if you have checked what it does
`exec` cannot be allowed casually	It is always classified destructive	Leave it Off unless you have a specific, reviewed reason
Write tools are missing	Read-only mode is on	Turn it off, or make a connection without it
A new PostHog tool is missing from the list	The list is stale; PostHog changed its catalog	Use Refresh actions, then check the new tool's setting — on a self-credentialed connection it arrives active under existing policy, so confirm it is where you want it
Queries time out or are throttled	PostHog's own query limits, not Paperclip's	Narrow the time range or the query

Limitations: one PostHog account per connection. Pinning restricts the project but not what the account could otherwise reach if you unpin. Query cost and rate limits are PostHog's.

5.6 KiB Raw Blame History