PaperClipAI/doc/connections/NEON.md

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.

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.

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.