Devin FoleyandPaperclip
5b8b2b38ca
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents reach external services through the Apps catalog. Each catalog entry is a reviewed `AppDefinition` that wires a provider's hosted MCP server into Paperclip's shared vault, grants, policies, gateway, and audit trail. > - Neon is a widely used serverless Postgres provider with an official hosted MCP server, but it is not in the catalog. Teams that run their databases on Neon must use the generic "connect your own MCP server" path, which has no branding, no guidance, and no project or read-only controls. > - The connector playbook requires a catalog entry for a provider like this: the hosted server supports dynamic client registration and bearer API keys, and the common definition fields can express every option Paperclip can serialize. > - This pull request adds the Neon definition, its official artwork, the research and permission-review ledger rows, documentation, and deterministic tests, without any provider-specific runtime code. > - The benefit is a one-click, governed Neon connection with optional project pinning and read-only mode, and a documented path to live qualification. ## Linked Issues or Issue Description **Problem or motivation** Neon is a common Postgres host for the applications agents work on, but Paperclip's Apps catalog has no Neon entry. Operators who want agents to inspect schemas, run SQL, or manage branches must paste the MCP URL into the generic remote-MCP flow, which gives no branding, no provider guidance, no project boundary, and no read-only switch. **Proposed solution** Add a catalog-only Neon connection built from the connector playbook: browser sign-in through Neon's dynamic client registration with the reviewed `read` and `write` scopes, or a customer API key sent as an Authorization bearer header. Both methods expose Neon's documented `projectId` pin and `readonly` switch as optional Advanced fields. Every discovered tool stays governed by the normal per-action policies. **Alternatives considered** A plugin was not needed because no custom UI, tables, workers, or webhooks are involved. A separate read-only method was not added because the playbook treats read-only switches as advanced fields rather than methods. Neon's repeatable `category` query filter was left out because tenant fields serialize lists as one comma-joined value, so it cannot be sent correctly without new runtime code; per-action policies cover catalog narrowing instead. **Roadmap alignment** This extends the existing self-serve remote-MCP connection catalog and does not overlap planned core work. ## What Changed - Added the `neon` provider to `scripts/ingest-app-definitions.mjs` (category, API-key placement, methods, tenant fields, guidance, warnings) and regenerated `packages/shared/src/app-definitions/neon.json` plus the generated registry. - Added the Neon row to the self-serve MCP research ledger with `dcr_or_api_key` auth and risk tier S4. - Added permission reviews for `neon/mcp-oauth` (explicit scopes `read`, `write`, taken from Neon's live authorization-server metadata) and `neon/mcp-api-key` (provider key), with evidence links. - Added Neon's official tile icon (`ui/public/brands/apps/neon.png`, copied byte-for-byte from the icon linked by neon.com) and the brand manifest entry. - Added prosumer gallery copy for the Neon card. - Added `doc/connections/NEON.md` (service involvement, endpoints, administrator setup, capabilities and policy, manifest, brand provenance, validation hook) and linked it from the connections README and the permission audit. - Tests: Neon definition shape, store visibility and artwork, URL recognition, reviewed scopes with scope-widening rejection, URL projection of the project pin and read-only flag, invalid project ID rejection, the connect form's API-key gating, and the pinned catalog counts. ## Verification - `pnpm exec vitest run packages/shared/src/app-definitions.test.ts packages/shared/src/app-definitions-url.test.ts` — 34 passed. - `pnpm exec vitest run server/src/__tests__/tool-access-service.test.ts` — 367 passed. - `pnpm exec vitest run ui/src/pages/apps/AppsConnect.test.tsx ui/src/pages/apps/Browse.test.tsx ui/src/lib/app-brand-assets.test.ts ui/src/pages/apps/AppLogo.brand-assets.test.tsx` — all passed. - `node scripts/check-app-brand-assets.mjs` and `node --test scripts/app-brand-validation.test.mjs` — passed. - `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter @paperclipai/server typecheck`, `pnpm --filter @paperclipai/ui typecheck`, `pnpm check:token-gates` — clean. - Manual: in a local instance, open Apps → Browse, confirm the Neon card and icon, open `/apps/connect?source=neon`, confirm both methods, the Advanced project pin and read-only toggle, and that Connect enables after an API key is entered. The operator completed a live connection against a Neon account on this build. - Live metadata probed on 2026-10-02: both `.well-known` documents at `mcp.neon.tech` return the recorded endpoints and scopes; an unauthenticated `initialize` returns 401 with `resource_metadata`. ## Risks - Low risk to existing providers: the change is additive catalog data plus tests. The generated registry only gains one import. - Neon's hosted server grants broad project and database management. The definition carries two warnings, recommends a development project, and keeps every write under the normal action policies; the read-only switch is enforced by Neon's server, not locally. - The permission-review ledger records live proof for both methods as not run; the full lifecycle checklist in `doc/connections/NEON.md` still needs a documented pass before the entry is considered fully qualified. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Fable 5.1 (`claude-fable-5-1`) in Claude Code, with extended thinking and tool use (shell, file editing, browser verification). ## 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 either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) 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 Co-authored-by: Paperclip <noreply@paperclip.ing>
13 KiB
Tool connection permission audit — 2026-09-30
This review covers 117 tool methods (84 OAuth methods). The machine-readable source of reviewed defaults lists each method's exact requested scopes, supported actions, restrictions, sources and verification limits. AI runtime authentication and chat/channel setup are separate contracts and were not changed.
Methods reviewed after this audit carry their own reviewedAt date in the same
ledger; the counts above are not restated. Later additions: Neon
(mcp-oauth, mcp-api-key; 2026-10-02).
Shared credential failure
Zapier's secret URL exposed a shared ownership/resolution problem. The same invariants apply to personal pasted-key and custom-header methods, including Bitly, Cloudflare, Coda, Fireflies, GitHub PATs, Kernel, O'Reilly, PagerDuty, PostHog, Postman, Razorpay, Sanity, Similarweb, Stripe, Supabase and You.com. Generic MCP setup uses this path too, so “Connect your own” was not a reliable workaround. This is a code-path finding, not a claim that every provider was tested with a live account.
Personal invocation secrets now belong to the grant's user. Setup, health, discovery and the run gateway share ownership checks and canonical credential paths. Public unauthenticated URLs need no credential repair. OAuth client registration secrets remain company-owned and separate from invocation tokens. Existing connections with incorrectly owned credentials require the owner to reconnect with a fresh key or secret URL. There is no automatic ownership backfill.
Changes
- Airtable now requests its seven documented record, schema, comment and workspace/base scopes, including writes.
- Explicit scope sets were added for providers that advertise a scoped MCP resource, including Beehiiv, Netlify, Miro, Sentry, Supabase, Todoist and TickTick. Read and write remain subject to provider roles and resource selection.
- Hugging Face adds repository read/contribution and jobs to
read-mcp. Optional tools still need enabling in HF's MCP settings. - Slack's reviewed set now covers the documented message, channel, reaction, canvas, file and list actions. It replaces the obsolete generic search scope with the documented search scopes. The fixed app/approval gate remains.
- Google write/draft methods take priority over managed read-only methods when available. Existing Google profiles, preview verification and availability gates remain. People and Workspace Search stay read-only.
- The hosted Fireflies server also exposes meeting sharing, renaming, moving and soundbite creation. Its identity scopes are retained; meeting ownership and team roles decide which mutations succeed.
- Provider read-only choices stay available under Advanced. Existing OAuth tokens and action restrictions are untouched. Permissions offers reconnect when provider consent needs changing.
Provider-default exceptions
These are deliberate exceptions to supplying scopesHint, not claims that an
old grant can write. Several servers put resource/permission selection in their
own consent screen; Box uses registered app scopes, and managed GitHub uses
installation permissions. An authorization server's general scope catalog is
not a safe substitute for the MCP permission contract.
| Provider / method | Reason and limits |
|---|---|
bitly / mcp-oauth |
The official MCP quickstart uses browser authorization without client-selected scopes; neither protected-resource nor authorization-server metadata advertises a scope list. Bitly account permissions govern link actions. Evidence |
box / mcp-own-oauth |
Box requires scopes (including Manage AI) on the registered Box app in the Admin Console. Its MCP authorization metadata has no request-scope list; consent and the app registration control file operations. Evidence |
egnyte / mcp-oauth |
The hosted authorization server selects the Egnyte tenant/account permissions. Neither MCP nor authorization-server metadata advertises request scopes. Documentation rendered no readable body during this review; tenant-bound write proof remains required. Evidence |
github / managed |
Managed github.code uses a GitHub App installation and selected repositories. Installation permissions, not OAuth scope strings, grant code and pull-request writes; retain the managed profile. Evidence |
make / mcp-oauth |
Make documents selecting scopes and scenarios during its hosted connection flow. Management tools require a paid plan. Do not replace that resource selection with invented MCP client scopes. Evidence |
oauth-generic / oauth |
Operator-defined OAuth endpoints have no provider-specific reviewed scope list. Request only the scopes supplied by the operator; this template is not a curated provider allowlist. Evidence |
planetscale / mcp-oauth |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
planetscale / mcp-insights-only |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
posthog / mcp-oauth |
PostHog documents the no-scope MCP setup as read/write, with optional readonly and feature filters. The authorization server advertises account administration unrelated to many tools; retain its MCP consent defaults and the existing explicit filters. Evidence |
postman / mcp-oauth-minimal |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-code |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-full |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
razorpay / mcp-oauth |
Neither protected-resource nor authorization-server metadata advertises scopes. Keep hosted provider consent; the previous official OAuth documentation URL returned 404 during review. Account-bound writes need live confirmation. Evidence |
ticket-tailor / mcp-oauth |
Hosted authorization controls box-office API-key permissions; do not treat OAuth sign-in as increasing the underlying key permissions. This method requires account-bound proof. Evidence |
webflow / mcp-oauth |
The official MCP setup installs the Bridge App and asks users to authorize sites. Neither protected-resource nor authorization-server metadata publishes a request-scope list; the installed app and site selection govern writes. Evidence |
Read-only and provider-controlled methods
Candid, Context7, O'Reilly, Similarweb and You.com expose retrieval/research capabilities rather than document/account mutation. PlanetScale's insights-only endpoint deliberately excludes query execution. Xero's current published MCP scope set includes invoice/report reads and settings access, without invoice write permission. Do not widen these using unrelated general API scopes.
Scopes such as openid, global, mcp:all or workspace:member do not have to
contain the word “write” to authorize work. The provider's MCP tool contract,
role and consent selection determine their meaning. In particular, Cloudflare,
Vercel, Wix, Kernel and Supermemory retain their provider-side permission gates.
Evidence and verification boundaries
Official docs and unauthenticated protected-resource/authorization metadata were retrieved on 2026-09-30. The review records source URLs per method. Some pages (especially Egnyte and Razorpay's old OAuth URL) were unavailable or unreadable; those entries explicitly retain that limitation. Embat publishes identity metadata but no verified write contract. No account-bound write guarantee is made for these entries.
No provider account was used for live read/write verification in this task. In particular, public scope metadata is not proof that an existing token has those permissions or that an account has the required paid plan, resource ACLs, admin approval, or Google preview enrollment. Use test accounts/resources for that proof before claiming provider-level acceptance.
Backend regressions execute catalog Zapier, generic secret URLs, personal bearer/custom headers, organization credentials and public URLs through the run-scoped gateway using a fixture transport. They assert canonical persisted ownership/declarations and run read and write calls. Reconnect regressions cover replacing legacy company credentials with user-owned values and declarations. OAuth fixtures assert exact authorization scopes and rejection of an unrelated advertised admin scope; they do not contact provider accounts.
The managed worktree has a separate instance configuration and database path.
Local CLI provisioning was attempted with both minimal and full seed modes;
both failed while applying the copied database's migrations because
tool_connections_transport_check was missing. The development instance was
not started from that clone. Clean fixture databases were used for the backend and Apps browser
checks; their success does not establish successful seeding of that local copy.
Embedded-browser acceptance
On 2026-09-30, a hands-on walkthrough used the PR checkout's built UI and actual server, a fresh isolated database created through CLI onboarding, and a local HTTP MCP fixture. Starting from the sidebar's Connectors page, the operator selected “Just me,” entered a bearer key, and created and read back a disposable widget through the Permissions screen's agent test controls.
After seeding the legacy ownership mismatch in that disposable connection,
invocation and catalog refresh rejected it with grant_credential_invalid.
The catalog showed “Needs attention” and offered Reconnect. Replacing the key
through that UI preserved the connection and personal grant, created a fresh
user-owned secret and canonical declaration, and restored writes. The legacy
company secret retained its ownership. Separate HTTP calls through a session
bound to a fixture agent run also completed a write and read-back.
The walkthrough exposed and verified fixes for a false “Still not working” message after successful reconnect, incorrect action-input advice for ownership errors, and Cancel attempting to save an invalid Zapier URL. The browser reconnect regression now performs the replacement through the form and checks that the stale warning disappears.
A second personal connection used a secret URL. After reproducing its legacy ownership failure, the browser could replace the URL and create/read back a widget. Generic reconnect now derives URL/header fields from the stored credential placement instead of assuming a bearer key, and rejects replacement URLs for a different public endpoint. A new public, organization-wide connection also appeared immediately when returning to Browse, without a page reload. The walkthrough fixed setup cache invalidation and a cramped reconnect banner.
Zapier's URL validation and cancellation were exercised, but a live Zapier connection was not completed. Gmail stopped at instance enrollment. Neither journey establishes provider-account consent or live provider read/write proof.
Automated verification
- Run
pnpm -r typecheck,pnpm build, andpnpm check:token-gates. - The affected Apps browser suites passed 10 tests, with one existing restart case skipped. These used clean, isolated fixture databases.
- Run
pnpm test:runfor the full suite. Current-head CI and local results are recorded in the pull request; fixture coverage is distinct from provider proof. - New gateway fixtures execute both read and write calls through real run-scoped gateway sessions. They also verify that invalid ownership requires reconnect and that the owner's fresh credentials restore access without changing identity.