Neon

Neon

This connector manages Neon serverless Postgres through the Neon API v2 (https://console.neon.tech/api/v2) with an API key: organizations, projects, branches, compute endpoints (start and suspend), databases, roles, database schemas, operations and consumption. It does not run SQL (see below).

Setup (about 2 minutes)

1. In the Neon Console open Account settings → API keys (personal key: acts as you, in every organization you belong to) or Organization settings → API keys (organization key: only that organization's projects; a project-scoped key: only one project).
2. Create the key, copy it at once (Neon shows it only once) and paste it into NEON_API_KEY.
3. Install and run neon_list_organizations.

Write tools need confirmation. Before neon_create_branch, neon_start_endpoint or neon_suspend_endpoint, tell the user what will happen and wait for a clear yes.

• A running compute uses compute hours (CU-hours), which count against the plan's allowance or are billed on paid plans; neon_start_endpoint starts that meter. Computes scale to zero by themselves after the suspend timeout.
• neon_suspend_endpoint closes every open connection to that compute at once.
• neon_create_branch creates a copy-on-write branch (instant, no data copied). Branches beyond the plan's allowance and their storage changes can be billed; adding an endpoint also starts a compute. Set expires_at for temporary branches.
• Switched off at install: neon_delete_branch (deletes the branch and its computes; the root and default branch cannot be deleted).

Finding things

• neon_list_organizations gives the org_ids. With a personal API key, neon_list_projects needs org_id for organization projects; with an organization key it is inferred.
• neon_list_projects → neon_get_project (settings and this period's usage) → neon_list_branches / neon_get_branch (the default branch has default: true) → neon_list_databases / neon_list_roles / neon_get_database_schema. Ids: projects like shiny-wind-028834, branches br-..., computes ep-....
• neon_list_endpoints (or neon_get_endpoint for one) shows each compute's state (active, idle), size range in CU and the host name.
• Every change runs as asynchronous operations: the answer lists them, and neon_get_operation shows when they finish (finished, failed).
• Lists page with cursor: pass pagination.next (branches) or pagination.cursor (projects, operations) from the previous answer.

Usage and cost: neon_get_consumption returns compute unit seconds, storage, branch counts and network transfer per project and period (hourly for the last 7 days, daily for 60 days, monthly for a year). It needs org_id and is available on paid plans only (Launch, Scale, Business, Enterprise). It does not wake computes. Project and branch details also show compute_time_seconds, active_time_seconds, written_data_bytes and data_transfer_bytes for the current period.

Passwords and connection strings are never returned. Role passwords, connection URIs and the reveal-password call are left out on purpose, so no database password reaches the AI.

Running SQL is not part of this connector. Neon's SQL over HTTP endpoint (https://<endpoint host>/sql) authenticates with a full Postgres connection string including the role's password, not with the API key, so it would put a database password in front of the AI. To query data, use the PostgreSQL connector with a dedicated read-only Postgres role on the Neon host (<endpoint host>, port 5432, SSL required). neon_get_database_schema still shows the tables and columns without a password.

Common errors

• 401 supplied credentials do not pass authentication: wrong or revoked API key. Neon answers 401 on every URL for a bad key.
• 403: the key may not access that project or organization (a project-scoped or organization key used elsewhere), or the plan does not include the feature (consumption history).
• 404: wrong project, branch or endpoint id. 423 Locked: another operation is running on the project; wait for it (neon_list_operations) and retry.
• 429: too many requests; wait a little and retry.

Out of scope here: SQL, creating or deleting projects, databases and roles, resetting role passwords, Neon Auth, the Data API, snapshots and organization administration.