feat(apps): add Neon connection (#14980)

## 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>
2026-10-06 10:48:12 +02:00 · 2026-10-02 15:04:52 -07:00
1 parent d6d88b9de2
commit 5b8b2b38ca
@@ -6,6 +6,10 @@ 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](./NEON.md)
+(`mcp-oauth`, `mcp-api-key`; 2026-10-02).
+
 ## Shared credential failure

 Zapier's secret URL exposed a shared ownership/resolution problem. The same
@@ -0,0 +1,237 @@
+# Neon
+
+Updated: 2026-10-02. Status: catalog definition reviewed against official
+documentation and live provider metadata; live account qualification
+outstanding.
+
+Neon appears in Apps and uses Paperclip's shared remote-MCP OAuth connection,
+vault, catalog, grants, policies, gateway, and audit trail. It is a resource
+connection, not Paperclip sign-in. No plugin, provider-specific runtime code,
+or database migration is required.
+
+Paperclip connects to Neon's hosted MCP server at `https://mcp.neon.tech/mcp`.
+The connection supports two explicit methods:
+
+- browser OAuth, recommended for Neon accounts; or
+- a Neon 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.
+
+This curated connection is the polished route: it provides branding, optional
+project pinning and read-only controls, field validation, and tailored
+guidance. None of it is *required* to reach Neon's server. Neon can also be
+connected generically from **Connect your own MCP server** by pasting
+`https://mcp.neon.tech/mcp`, with no Paperclip-specific code involved. See
+[Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md).
+
+## Service involvement
+
+Neon hosts both the MCP resource and its OAuth authorization service on the
+same origin. Paperclip discovers the OAuth endpoints, dynamically registers the
+client, stores returned credentials as secret references, and handles the
+callback at `/api/tools/oauth/callback`. No Paperclip-operated vendor relay is
+involved; cloud and self-hosted instances use the same path.
+
+```mermaid
+sequenceDiagram
+    actor A as Administrator
+    participant P as Paperclip
+    participant M as mcp.neon.tech
+
+    A->>P: Choose Sign in with Neon
+    P->>M: GET /.well-known/oauth-protected-resource/mcp
+    M-->>P: Authorization server: https://mcp.neon.tech
+    P->>M: GET /.well-known/oauth-authorization-server
+    M-->>P: authorize, token, register, revoke endpoints; scopes read, write
+    P->>M: POST /api/register (dynamic client registration)
+    M-->>P: Client registration
+    P-->>A: Open browser authorization (scope: read write, PKCE S256)
+    A->>M: Approve access
+    M-->>P: Redirect to /api/tools/oauth/callback
+    P->>M: POST /api/token (authorization code)
+    M-->>P: Access and refresh tokens
+    P->>M: tools/list on /mcp with optional projectId and readonly query
+    M-->>P: Neon tool catalog
+```
+
+The hosted endpoints retrieved on 2026-10-02:
+
+| Purpose | Endpoint |
+| --- | --- |
+| MCP resource (Streamable HTTP) | `https://mcp.neon.tech/mcp` |
+| Protected-resource metadata | `https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp` |
+| Authorization-server metadata | `https://mcp.neon.tech/.well-known/oauth-authorization-server` |
+| Authorize | `https://mcp.neon.tech/api/authorize` |
+| Token | `https://mcp.neon.tech/api/token` |
+| Dynamic client registration | `https://mcp.neon.tech/api/register` |
+| Revoke | `https://mcp.neon.tech/api/revoke` |
+| Paperclip callback | `/api/tools/oauth/callback` |
+
+The authorization server advertises `code` responses, PKCE `S256`,
+`authorization_code` and `refresh_token` grants, `none` client authentication
+for registered public clients, and exactly two scopes: `read` and `write`.
+Paperclip requests both so the connection has the write surface described
+below; the read-only switch narrows the server itself rather than the token.
+Caller widening beyond the reviewed scopes is rejected.
+
+Neon's older SSE endpoint (`https://mcp.neon.tech/sse`) is deprecated and
+returns `410 Gone` on or after 2026-10-01. Paperclip does not offer it.
+
+## Administrator setup
+
+1. In **Apps → Browse**, choose **Neon**.
+2. Explicitly choose **Sign in with Neon** or **Use an API key**.
+3. Continue directly with Neon's defaults. No project ID is required.
+4. Open **Advanced** only when you need to pin the connection to one
+   **project ID** or force **Read-only mode**.
+5. For OAuth, continue through browser consent. For API-key setup, create a
+   key in Neon Console → **Settings → API keys** and paste it into Paperclip.
+   Prefer a project-scoped key, which Neon limits to one project with Editor
+   rights; personal and organization keys reach every project the account can
+   access. Never put the key in connection configuration or a URL.
+6. Review discovered actions on the connection's **Permissions** screen. Every
+   discovered action starts **Allowed**, including writes and destructive
+   actions. Set deletion, branch reset, and compute mutations to **Ask first**
+   where operator review is wanted.
+
+Use a public HTTPS Paperclip origin or a loopback HTTP origin such as
+`http://localhost:3100`. A plain HTTP tailnet hostname is not loopback; use
+HTTPS or change the local canonical origin before connecting.
+
+When configured, Paperclip appends `projectId=<id>` and `readonly=true` as
+query parameters on the server URL, exactly as Neon documents. The same URL is
+used for catalog discovery and tool execution, and a caller cannot override it.
+Neon documents a repeatable `category=<name>` filter as well; Paperclip's
+tenant fields serialize lists as one comma-joined value, so that filter is not
+offered. Use the per-action Off / Ask first / Allowed controls to narrow the
+catalog instead.
+
+## Capabilities and policy
+
+The catalog is discovered live from the actual provider schemas. Neon groups
+its tools into these categories:
+
+| Category | What the tools do | Classification |
+| --- | --- | --- |
+| `docs` | Look up Neon documentation | Read |
+| `schema`, `observability` | Inspect tables and columns, compare schemas, query logs, check availability | Read; may expose application data |
+| `projects`, `branches`, `endpoints` | List, create, describe, delete projects and branches; manage roles, databases and computes | Write or destructive |
+| `snapshots` | Create, restore and schedule snapshots | Write or destructive |
+| `querying` | Execute SQL, apply schema changes, run diagnostics | Write; read-only mode limits SQL to `SELECT` |
+| `neon_auth`, `data_api` | Provision Neon Auth, manage OAuth providers, enable or disable the Data API | Write |
+| `functions`, `storage` | Deploy functions, manage buckets and objects | Write or destructive |
+
+Neon enforces the account, organization, and project permissions behind the
+credential. The optional project pin and read-only switch are enforced by
+Neon's server, not by Paperclip. `requiredResourceFilters: ["project"]` is
+reviewed policy metadata that names the boundary operators should set; it is
+not a local allowlist.
+
+Neon's own guidance: the hosted server grants broad database management
+capabilities, so always review and authorize actions before execution, and
+prefer development or testing projects over production data.
+
+## Vendor
+
+- App key: `neon`
+- App name: Neon
+- Reuse classification: MCP-direct
+- Reason for classification: official hosted Streamable HTTP server with
+  RFC 7591 dynamic registration and documented bearer API keys; common fields
+  represent every documented option Paperclip can serialize.
+- Security tier: S4
+- Plugin needed? No.
+
+## Transport and auth
+
+- Transport: `mcp_remote`
+- Endpoint: `https://mcp.neon.tech/mcp`
+- Auth modes: OAuth (DCR, PKCE) or API key
+- OAuth scopes: `read`, `write` (explicit, reviewed)
+- Key scope: whatever the Neon key carries; Paperclip cannot widen it
+- Credential owner: company or user grant through the standard access screen
+- Secret storage: `company_secrets` refs only
+- Revocation: Neon publishes `/api/revoke`; Paperclip removal revokes the
+  grant and deletes stored secrets
+
+## Resource filters
+
+- Required filters: none on the default path
+- Optional filters: `projectId` (query `projectId`), `readOnly` (query
+  `readonly=true`, omitted when off)
+- Write-enabling filters: none; writes depend on the credential and on
+  read-only mode being off
+- Filters enforced by: Neon's hosted server
+
+## Manifest
+
+- slug: `neon`; name: Neon; categories: `data`
+- branding: `/brands/apps/neon.png` (official touch icon, both themes)
+- docsUrl: `https://neon.com/docs/ai/neon-mcp-server`
+- methods: `mcp-oauth` (Sign in with Neon, `dcr`), `mcp-api-key` (Use an API
+  key, `customer`, `Authorization: Bearer` header)
+- tenantFields: `projectId` (text, advanced, `^[a-z0-9-]+$`, max 64),
+  `readOnly` (checkbox, advanced, default off)
+- riskTier: S4; requiredResourceFilters: `project`
+- urlPatterns: `https://mcp.neon.tech/*`; redirectConstraints:
+  `https-or-loopback-http`
+
+Source of truth: the `neon` block in `scripts/ingest-app-definitions.mjs`, the
+ledger row in `packages/shared/src/self-serve-mcp-research.json`, and the two
+reviews in `doc/connections/tool-method-permission-reviews.json`. Regenerate
+with `pnpm connections:ingest-app-definitions` (or `--definitions-only`
+without the research corpus).
+
+## Wizard path
+
+- User path: Apps → Browse → Neon → method → Access → Connect.
+- Configuration steps: none required; Advanced holds project pin and
+  read-only mode.
+- Error states: discovery or OAuth failures stay inline on Connect with a
+  retry of the same saved connection; an invalid project ID is rejected before
+  the provider is contacted.
+- Redacted metadata shown: method, pinned project ID, read-only flag. Tokens
+  and keys are never shown.
+
+## Governance defaults
+
+- Default profile and bindings: the standard connection profile; every
+  discovered action starts Allowed under the current product default.
+- Policies: operators narrow destructive categories to Ask first or Off on the
+  Permissions screen.
+- Quarantine rules: the shared defaults; no Neon-specific exceptions.
+
+## Brand provenance
+
+Neon's own app icon, the black tile with the green logomark, is used because the
+bare logomark from the brand kit is a thin outline that reads weakly at 24–36px
+on the light frame. The file is Neon's official touch icon, copied byte-for-byte
+on 2026-10-02 and used unchanged in both themes (Neon's brand colours are
+black and `#34D59A`).
+
+| File | Source | SHA-256 |
+| --- | --- | --- |
+| `ui/public/brands/apps/neon.png` (180×180) | `https://neon.com/apple-touch-icon.png`, the icon linked from `https://neon.com/` | `a6cf4b0772b06a5a64ccfefbfb8b7a1af56e0876eb10c9052f43c8624f4a0b61` |
+
+The brand kit at `https://neon.com/brand` publishes the bare logomark as SVG
+(light and dark colour variants) but no vector of the tile; the raster official
+icon is preferred over a locally composed SVG so the artwork stays the
+vendor's own.
+
+## Validation hook
+
+- Environment: definition review on 2026-10-02 against `origin/master`;
+  no Neon account was used.
+- Metadata probe: both `.well-known` documents above returned HTTP 200 with the
+  endpoints and scopes recorded here. An unauthenticated `initialize` on
+  `/mcp` returned HTTP 401 with
+  `WWW-Authenticate: Bearer ... resource_metadata="https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp"`.
+- Deterministic tests: manifest shape, store visibility, artwork, reviewed
+  scopes, scope-widening rejection, URL projection of the project pin and
+  read-only flag, and invalid project ID rejection.
+- Connect evidence, catalog evidence, allowed read, governed write,
+  denied case, revoke, audit: not run. Each exposed method still needs the
+  full live lifecycle with a Neon development project before this connection
+  is considered qualified.
@@ -13,7 +13,7 @@ Runtime authentication: [AI Connections](./AI-CONNECTIONS.md).
 Long-term memory: [Experimental memory connectors](./MEMORY.md).

 Provider notes: [Google Workspace](./GOOGLE-WORKSPACE.md),
-[Gmail](./GMAIL.md), [Asana](./ASANA.md), [PostHog](./POSTHOG.md),
+[Gmail](./GMAIL.md), [Asana](./ASANA.md), [PostHog](./POSTHOG.md), [Neon](./NEON.md),
 [AgentMail](./AGENTMAIL.md), and [iMessage Photon](./IMESSAGE-PHOTON.md). Optional credential custody:
 [Vercel Connect](./VERCEL-CONNECT.md).

@@ -1368,6 +1368,42 @@
      "reviewedAt": "2026-09-30",
      "liveProof": "not-run"
    },
+    {
+      "app": "neon",
+      "method": "mcp-oauth",
+      "auth": "oauth",
+      "policy": "explicit",
+      "requestedScopes": [
+        "read",
+        "write"
+      ],
+      "capability": "write",
+      "supportedActions": "Create, describe and delete projects and branches; manage computes, roles, databases and snapshots; run SQL and apply schema changes; configure Neon Auth and the Data API; read logs. Optional project pinning and read-only mode narrow the hosted server.",
+      "evidence": [
+        "https://neon.com/docs/ai/neon-mcp-server",
+        "https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp",
+        "https://mcp.neon.tech/.well-known/oauth-authorization-server"
+      ],
+      "reviewedAt": "2026-10-02",
+      "liveProof": "not-run"
+    },
+    {
+      "app": "neon",
+      "method": "mcp-api-key",
+      "auth": "api_key",
+      "policy": "provider-key",
+      "requestedScopes": [],
+      "capability": "provider-controlled",
+      "supportedActions": "Create, describe and delete projects and branches; manage computes, roles, databases and snapshots; run SQL and apply schema changes; configure Neon Auth and the Data API; read logs. Optional project pinning and read-only mode narrow the hosted server.",
+      "evidence": [
+        "https://neon.com/docs/ai/neon-mcp-server",
+        "https://neon.com/docs/manage/api-keys",
+        "https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp"
+      ],
+      "reviewedAt": "2026-10-02",
+      "liveProof": "not-run",
+      "keyPermissions": "Project, branch, compute, snapshot, SQL and schema changes within the key\u2019s reach. A project-scoped key limits access to one project with Editor rights; personal and organization keys reach every project they can access. Paperclip cannot increase an existing key\u2019s permissions."
+    },
    {
      "app": "notion",
      "method": "mcp-oauth",