neon-postgres-agent-platforms

# Neon AI Agent Program Companion to `**neon-postgres**` (install that first). This skill covers fleet-scale control plane for the Neon Agent Program: dual-org layout, project transfer, per-tenant provisioning, compound checkpoints, consumption, commercial terms, and when to give agents Management API access via `@neon/tools`. For connection strings, drivers, ORMs, branching tutorials, Auth in apps, Data API, and Neon's hosted MCP, use `**neon-postgres**` and [Neon docs](https://neon.com/docs). ## Scope Use `**neon-postgres**` for general Neon usage. Use **this skill** when the question involves: - Dual-org economics and API keys (personal, organization, project-scoped) - `@neon/sdk` for the control plane vs `@neon/tools` for agent-facing Management API access - Project-per-tenant provisioning and transfer - Fleet-wide snapshot/restore orchestration and housekeeping - Compound checkpoints - Consumption polling for metered fleets - Agent Plan commercial terms (with links, not invented numbers) - Partner support paths ## Install Skills ```bash npx skills add neondatabase/agent-skills -s neon-postgres ``` ## Assistants: what you can do after install With `**neon-postgres**` and **this skill** loaded, you have enough context for platform-level Neon work: dual-org layout, provisioning a project for a new tenant, compound checkpoints, org-wide consumption polling, and transfer/upgrade flows—without the user pasting long documentation. **Where runnable examples live:** TypeScript samples run from this skill’s [`scripts/`](https://github.com/neondatabase/neon-for-agent-platforms/tree/main/skills/neon-postgres-agent-platforms/scripts) directory (`package.json`, `npm run …`). The `**references/**` directory keeps markdown guides beside the runnable examples; [MANAGEMENT_API_SAMPLES.md](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/MANAGEMENT_API_SAMPLES.md) is the script catalog and env map. The human **Quick start** is the root [README](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/README.md#quick-start). ## SDK vs agent tools Your control plane should call [`@neon/sdk`](https://www.npmjs.com/package/@neon/sdk). The sample scripts in this repo do. The [Neon MCP server](https://github.com/neondatabase/mcp-server-neon) is a custom agent-facing layer: MCP tool handlers written over `@neon/sdk`. Use [`@neon/tools`](https://www.npmjs.com/package/@neon/tools) when you want to give agents on your platform direct Neon management access without writing those handlers. It publishes generated wrappers for a selected set of SDK methods as agent tools, with adapters for MCP, Eve, and Mastra. These public client methods are not tools: `projects.create`, `branches.create`, `operations.waitFor`, `postgres.roles.password`, and `storage.objects.get`. Use `projects.createAndConnect` and `branches.createWithCompute` for creates that attach compute and return a connection string. Waiting is what the write tools already do. Generated schemas are strict: a newly added API field is rejected until you upgrade `@neon/tools`, or call `@neon/sdk` directly. Selectors are SDK paths (`projects.list`). Call `publishedId` for the model-facing id (`projects.list` → `list_projects`). `toolIds` lists every selector. MCP 2.x uses `@neon/tools/mcp`; MCP 1.x uses `@neon/tools/mcp-v1`. ```ts import { McpServer } from "@modelcontextprotocol/server"; import { createNeonTools } from "@neon/tools"; import { registerNeonTools } from "@neon/tools/mcp"; const apiKey = process.env.NEON_API_KEY; if (!apiKey) throw new Error("NEON_API_KEY is required"); const tools = createNeonTools({ apiKey, tools: [ "projects.list", "projects.createAndConnect", "branches.createWithCompute", ] as const, }); const server = new McpServer({ name: "neon", version: "1.0.0" }); registerNeonTools(server, tools); ``` `apiKey` accepts a function so a short-lived token can be refreshed per request. A remote MCP server that already authenticated the client can omit `apiKey` at construction; `registerNeonTools` then sends `authInfo.token`. MCP annotations are advisory. Hosts using `@neon/tools/mcp` must read `neon/requiresApproval` in MCP `_meta` and enforce their own approval policy before execution. The Eve and Mastra adapters map that flag to Eve's `approval` hook and Mastra's `requireApproval`. Every non-read operation is marked as requiring approval, as are reads that return connection credentials. Select only the methods each agent needs. For a tenant-scoped agent, inject the path `project_id` so the model cannot pick another project on tools that take that path parameter: ```ts const tools = createNeonTools({ apiKey, tools: ["projects.get", "branches.createWithCompute"] as const, inject: { projectId: tenantProjectId, omitFromSchema: true, }, }); ``` `inject.projectId` fills URL path `project_id` only. It does not hide query or body fields with that name, and it does not constrain tools that have no project path (for example `projects.list`). Pair it with a **project-scoped API key** when the agent must not see the rest of the org. Full API: [`@neon/tools` README](https://github.com/neondatabase/neon-pkgs/tree/main/packages/tools#readme). ## Gotchas Non-obvious facts agents often get wrong: - **Checkpoints are compound records.** A tenant checkpoint includes source revision + Neon snapshot/branch + secrets/env version + deploy URL + agent metadata. Do not equate "checkpoint" with "Neon branch" alone. See the [compound checkpoints doc](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md). - **Cross-org transfer** needs a **personal** API key (org keys only work inside one org). Projects with **GitHub or Vercel** integrations in Neon **cannot be transferred**; the API returns **422** ([Transfer projects](https://neon.com/docs/manage/orgs-project-transfer.md)). - **After a finalized snapshot restore**, the active branch ID changes. Poll operations to completion before reconnecting. Delete orphaned `(old)` branches to avoid storage cost. - **Billing-aligned usage:** prefer `GET /api/v2/consumption_history/v2/projects` over legacy consumption endpoints. The legacy account-level endpoint has been retired; use the v2 **per-project** endpoint ([legacy consumption guide](https://neon.com/docs/guides/consumption-metrics-legacy.md)). - **V2 `metrics` parameter values** (for implementers): `compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`, `instant_restore_bytes_month`, `snapshot_storage_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`, `extra_branches_month` ([consumption metrics](https://neon.com/docs/guides/consumption-metrics.md#required-parameters)). - **Snapshot schedules** are not provided on Agent Plan. Partners implement via snapshot API + their own scheduler. - **Rates and caps:** never invent dollar amounts or limits. Confirm on live neon.com docs. ## Agent Plan and two organizations Partners run **two Neon organizations**: | Org | Role | | ---------------------- | ------------------------------------------ | | **Sponsored free org** | Free-tier end users (within program rules) | | **Paid org** | Paying customers (metered per Agent Plan) | Key points: - Dollar rates, credits, and project caps come only from the live [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) and [neon.com/agents](https://neon.com/agents). Do not invent numbers. - **Organization API key:** automation inside one org (create project, set quotas). - **Personal API key:** required to transfer a project between orgs when a customer changes tier, then PATCH quotas to match the new tier. - **Project-scoped API key:** [member-level access](https://neon.com/docs/manage/api-keys.md#create-project-scoped-organization-api-keys) to **one** project only—narrower than an org key and useful for per-tenant runtime or automation that must not touch the rest of the org. Cannot create new projects org-wide; invalid if the project is transferred out of the org. Links: [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) · [AI Agents](https://neon.com/use-cases/ai-agents) · [Project transfer](https://neon.com/docs/manage/orgs-project-transfer.md) · [AI Agent integration](https://neon.com/docs/guides/ai-agent-integration.md) ## HIPAA - **Agent Plan includes HIPAA** with no extra fee. Partners must still follow Neon's published HIPAA program (workflows, agreements, configuration). - To get access or start the process, reach out to your **primary Neon contact**. - This skill is not legal advice. Link: [HIPAA on Neon](https://neon.com/docs/security/hipaa.md) ## Fleet shape: project-per-tenant - **Project-per-tenant** is Neon's documented fleet pattern: each **tenant** you provision for (an end **user**, a customer **app**, or an **agent** workload) gets its own **dedicated Neon project**. That project is the isolation boundary for **branches**, **databases**, **roles**, and **computes**—not a shared Postgres cluster where you only partition by schema. - **Isolation and billing:** Separate projects give **complete data and resource isolation** between tenants, keep **consumption limits and billing** straightforward at project scale (aligned with Agent Plan metering elsewhere in this skill), and match **how the Neon Management API and Console are structured** (project-scoped create, quota, and lifecycle calls). ### Staging and production - For **each** tenant project, treat **staging versus production** (and ephemeral **previews**) as **branch- and snapshot-driven** lifecycle inside that project—use **Snapshots and database versioning** and **Sandbox and preview databases** below for fleet orchestration, not a second project by default. - **Agent and app builders:** separate **your platform's** environments (for example how you host the builder or control plane) from **each tenant's** staging and production **branches**—avoid conflating "our production service" with "the tenant's production branch" in ledgers and automation. - Some **embedded** products also split an end customer's **production and development** Neon assets across **separate orgs** for trust, keys, and billing boundaries; when that applies, read **Isolation beyond branches (project and org edge cases)** next. Link: [AI Agent integration guide](https://neon.com/docs/guides/ai-agent-integration.md) ## Isolation beyond branches (project and org edge cases) Use **project-** or **org-level** splits when tenant scope or trust needs go beyond **branch- and snapshot-first** staging and production in **Fleet shape**. **Embedded** products may isolate an end customer's **production versus development** databases across **separate Neon orgs**, not only branches—tighter billing, org API keys, and console boundaries while you still manage branches **within** each org. **Project-level isolation (multiple projects per tenant or workload):** - Stronger **blast radius** if a connection string or role is compromised—one leak should not span unrelated workloads. - **Separate operational lifecycles** (for example a disposable analytics or migration sandbox versus production data) when automation or ownership would otherwise collide in one Postgres. - **Different teams or automation** with conflicting migration or admin rights. - **Harder compliance or data-mixing rules** where a single database must not host combined workloads. Each extra project adds fleet surface area: more API keys, more consumption rows, more housekeeping, and higher operational cost—keep **project-per-tenant** as the default unless a boundary above clearly applies. **Org-level isolation (beyond sponsored free versus paid):** - The **two-organization** layout in **Agent Plan and two organizations** is the commercial split (free-tier users versus paying customers). That pattern can **stack** with an embedded product split: for example **prod org versus dev org per end customer** so playground databases never share org scope with shipped production. Keep a clear internal map of which org owns which environment and tier. - Separately, partners sometimes need **additional Neon orgs or accounts** for contracting (enterprise “their org only”), reseller or MSP models, or geographic or legal separation—product defaults and limits belong on live docs; do not invent caps. - **Organization API keys are scoped to one org.** Cross-org moves use a **personal** API key and project transfer, as in **Gotchas**—do not assume an org key can operate across orgs. **Project-scoped** keys are further limited to a single project ([API keys](https://neon.com/docs/manage/api-keys.md)). **Embedding hygiene:** - Map each platform service (control plane, tenant runtime, billing or consumption jobs) to **least-privilege** keys; do not reuse production keys in sandboxes at the wrong layer. - When prod and dev for an end customer live in **different Neon orgs**, scope automation per org (typically **one organization API key per org**) and persist `org_id` with `project_id` / `branch_id` so jobs and restores target the correct side. - Keep your ledger (`project_id`, `branch_id`, org, checkpoint metadata) aligned with the isolation layer you chose so restores, transfers, and audits stay consistent. ## Snapshots and database versioning For snapshot semantics, active-branch patterns, and restore tutorials, defer to `**neon-postgres`** and [AI database versioning](https://neon.com/docs/ai/ai-database-versioning.md). Here, emphasize tenant fleets: - Persist snapshot and branch IDs per tenant in your ledger. Tie each to non-Neon state via [compound checkpoints](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md). - After finalized restores, branch IDs change and orphaned `(old)` branches accumulate. Automate cleanup and update stored IDs. - Poll operations to completion before reconnecting tenant apps. - Product semantics (snapshot counts per tier, Beta pricing dates) change. Confirm on [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) docs. Typical platform-level checkpoint triggers: - Before promoting generated schema changes for a tenant - Start or end of an agent run that mutates a tenant's database - Before destructive migrations or customer-visible restore actions Links: [AI database versioning](https://neon.com/docs/ai/ai-database-versioning.md) · [Backup and restore](https://neon.com/docs/guides/backup-restore.md) · [Snapshots-as-checkpoints demo](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo) ## Sandbox and preview databases Use this when a partner needs per-tenant preview or sandbox databases for generated apps. ("How do I create a branch?" for a single app goes to `**neon-postgres**`.) - Track `project_id` / `branch_id` per customer / agent run when spinning previews via the Management API. - Branch and storage counts scale with fleet size. Monitor caps and garbage-collect idle previews. - Short `suspend_timeout_seconds` on preview computes reduces cost. - Pair branch/snapshot lifecycle with secrets rotation and deploy URLs via compound checkpoints. Link: