Neon Postgres Projects & Branches
Spin up a copy-on-write Postgres branch for a preview deploy or a risky migration, then see what it holds. Browse Neon projects, branches, databases and roles, check compute endpoints and wake or suspend them, and follow branch operations until they finish.
Connect this API to an AI agent Browse all specs
What you can do with Neon Postgres Projects & Branches via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /projects |
listProjects | List projects (pass org_id for organization projects) |
| GET | /projects/{project_id} |
getProject | Get a project's region, Postgres version and settings |
| GET | /projects/{project_id}/branches |
listBranches | List a project's branches |
| POST | /projects/{project_id}/branches |
createBranch | Create a branch (optionally from a point in time) with a compute endpoint |
| GET | /projects/{project_id}/branches/{branch_id} |
getBranch | Get a branch's parent, size and state |
| GET | /projects/{project_id}/branches/{branch_id}/databases |
listBranchDatabases | List the databases on a branch |
| GET | /projects/{project_id}/branches/{branch_id}/roles |
listBranchRoles | List the Postgres roles on a branch |
| GET | /projects/{project_id}/endpoints |
listEndpoints | List compute endpoints with host, size and state |
| POST | /projects/{project_id}/endpoints/{endpoint_id}/start |
startEndpoint | Wake a suspended compute endpoint |
| POST | /projects/{project_id}/endpoints/{endpoint_id}/suspend |
suspendEndpoint | Suspend a compute endpoint to stop compute usage |
| GET | /projects/{project_id}/operations |
listOperations | List recent operations and their status |
Authentication
neonApiKey
Bearer token — sent as Authorization: Bearer <token>
Neon API key sent as Authorization: Bearer <key>.
How to get a credential
- In the Neon Console, open Account settings > API keys for a personal key, or Organization settings > API keys for an organization key (recommended for shared projects).
- Click Create new API key, name it (e.g.
VX Agents) and copy it; it is shown only once. - A project-scoped organization key limits access to a single project.
Permissions used
Neon API keys are not scoped per endpoint; a key can do everything its owner (or organization) can.
| Access | Operations |
|---|---|
| Read | listProjects, getProject, listBranches, getBranch, listBranchDatabases, listBranchRoles, listEndpoints, listOperations |
| Write | createBranch, startEndpoint, suspendEndpoint |
Common errors
- 401 Unauthorized: missing, revoked or mistyped API key.
- 403 Forbidden: a personal key used on an organization project it cannot see, or a project-scoped key used on another project. Pass
org_idtolistProjectsfor organization projects. - 400 / 422: invalid body, e.g. a
parent_lsn/parent_timestampoutside the history retention window. - 423 Locked: another operation is still running on the project; wait for it (see listOperations) and retry.
- 429 Too Many Requests: rate limit reached; back off and retry.
Store the key as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a Bearer credential: a Neon API key (Account settings > API keys, or Organization settings > API keys).
- Pin
project_id(e.g.wild-sky-123456, from Project settings orlistProjects) if you work in one project. For organization projects,listProjectsneedsorg_id(org-...).
Branch for a preview or migration
listProjects(filter withsearch) andgetProjectfor region and Postgres version.listBranchesto find the parent (usually the default branch, oftenmain; ids look likebr-...).- Show the user the plan and wait for confirmation, then
createBranchwithbranch: {"name": "preview/pr-42", "parent_id": "br-..."}andendpoints: [{"type": "read_write"}]so the branch gets a compute endpoint. Addbranch.parent_timestamp(ISO 8601) to branch from a point in the past, orbranch.expires_atso it cleans itself up. - The response lists
operations; polllistOperationsuntil they showfinishedbefore connecting. listBranchDatabasesandlistBranchRolesto tell the user which database and role to connect with;listEndpointsgives the endpointhost.
Control compute
listEndpointsshows each endpoint'scurrent_state(active,idle) and autoscaling limits.startEndpointwakes an idle endpoint;suspendEndpointstops it (open connections are dropped). Confirm with the user before either.
Good to know
- Ids: projects are slugs like
wild-sky-123456, branchesbr-..., endpointsep-.... - Times are ISO 8601 UTC. Lists page with
cursorandlimit. - A
423 Lockedresponse means another operation is still running on the project: wait and retry. - Creating branches and running compute can count toward your Neon plan's limits and bill.
createBranchwith an endpoint may returnconnection_uristhat contain a role password: never repeat them in chat unless the user asks.- This spec cannot delete, reset or reveal passwords.
Source: Neon API reference (https://api-docs.neon.tech/reference/getting-started-with-neon-api), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Neon Postgres Projects & Branches” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.