--- name: neon-postgres-agent-platforms description: >- Build and operate multi-tenant AI agent platforms on Neon. Use this skill whenever the user is designing an agent/app builder, provisioning a Neon project or database per user/app/agent run, managing thousands of tenant projects, separating sponsored free users from paid customers, moving projects between orgs, choosing `@neon/sdk` vs `@neon/tools`, choosing personal vs organization vs project-scoped API keys, tracking fleet consumption or Agent Plan costs, configuring scale to zero (`suspend_timeout_seconds`) for tenant databases, creating compound checkpoints that combine DB snapshots with source revisions/secrets/deploy metadata, or orchestrating snapshot/restore flows for generated apps. Also use it for Neon Agent Program, Agent Plan, org/project limits, HIPAA, co-marketing, support, or neondatabase/neon-for-agent-platforms examples. license: Apache-2.0 --- # 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)). - **Scale to zero is `suspend_timeout_seconds`**, not `autoscaling_limit_min_cu: 0`. The minimum compute size is `0.25` CU. See **Scale to zero** below. - **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. ## Scale to zero Default tenant databases to scale to zero. On agent and dev platforms most tenant databases are idle most of the time, and a suspended compute accrues no compute time, so fleet compute cost follows actual use instead of database count. Scale to zero is `suspend_timeout_seconds` on the compute endpoint. `autoscaling_limit_min_cu` cannot be `0`: its minimum is `0.25` and the API rejects lower values. | `suspend_timeout_seconds` | Behavior | | --- | --- | | `0` | Plan default, 300 seconds | | `60` to `604800` | Suspend after this many idle seconds; the lowest allowed value depends on the plan | | `-1` | Never suspend | Set it in `default_endpoint_settings` when you create the tenant project: ```ts import { createNeonClient } from "@neon/sdk"; const neon = createNeonClient({ apiKey, throwOnError: true }); const { project } = await neon.projects.createAndConnect({ name: `tenant-${tenantId}`, org_id: orgId, default_endpoint_settings: { autoscaling_limit_min_cu: 0.25, autoscaling_limit_max_cu: 2, suspend_timeout_seconds: 300, }, }); ``` `default_endpoint_settings` applies to computes created after it is set. Update existing computes directly: ```ts await neon.postgres.endpoints.update({ projectId, endpointId, suspend_timeout_seconds: 300, }); ``` Tradeoffs of keeping it on: - **Usage-based cost:** a suspended compute bills no compute time. An always-on compute bills around the clock, idle or not. - **Cold start:** the first connection after a suspend waits while the compute wakes, generally a few hundred milliseconds and longer after more than 7 days idle. Postgres memory buffers start cold, so early queries can be slower until they warm. - **Session state resets** on suspend: temporary tables, prepared statements, and in-memory statistics are gone. Long-running servers that hold a connection pool must reconnect on error. - **Anything that queries the database periodically keeps it awake**: health checks, keepalive queries, and logical replication subscribers. Which default to pick: - **Agent platforms, app builders, and dev platforms:** keep scale to zero on for every tenant project, free and paid. Generated apps, previews, and dev branches get sporadic traffic. - **Tenant production databases** with steady, latency-sensitive traffic, or that depend on session state across idle periods, may be better off with `-1`. Offer that as a per-project setting for paying customers rather than a fleet-wide default. - Plan limits on the timeout, and on disabling suspend, are in [AI Agent integration](https://neon.com/docs/guides/ai-agent-integration.md#project-limits-by-organization) and [Scale to zero](https://neon.com/docs/guides/scale-to-zero-guide.md). ## 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: [AI Agent integration guide](https://neon.com/docs/guides/ai-agent-integration.md) ## Cost, consumption, and entitlements - **Never invent** pricing, quotas, or limits. Confirm on [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) and [consumption metrics](https://neon.com/docs/guides/consumption-metrics.md). - Use `GET /api/v2/consumption_history/v2/projects` for billing-aligned fields. Legacy endpoints differ. The legacy account-level endpoint has been retired; use v2 per-project metrics instead ([legacy guide](https://neon.com/docs/guides/consumption-metrics-legacy.md)). - V2 `metrics` query strings are exactly: `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`. - Poll consumption roughly every 15 minutes. Polling does not wake suspended computes. - Run `auth-users.ts meta` from [scripts/](https://github.com/neondatabase/neon-for-agent-platforms/tree/main/skills/neon-postgres-agent-platforms/scripts) for a routing map (Neon Auth REST vs Postgres roles vs consumption APIs). Links: [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) · [Consumption metrics](https://neon.com/docs/guides/consumption-metrics.md) · [Consumption limits](https://neon.com/docs/guides/consumption-limits.md) · [Cost optimization](https://neon.com/docs/introduction/cost-optimization.md) · [Plans](https://neon.com/docs/introduction/plans.md) ## Organization and project limit increases - Current defaults and ceilings are on [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) and [AI Agent integration](https://neon.com/docs/guides/ai-agent-integration.md). Do not invent limits. - For project increase requests, email [agents@neon.tech](mailto:agents@neon.tech) with org ID(s), growth context, and timeline. Also flag in shared Slack if available. ## Co-marketing - Co-marketing is an included Agent Plan benefit. - Available: joint blog posts, social promotion, hackathon sponsorship, case studies, landing page features. - Reach out via shared Slack or your Neon representative with context on what you're building. Link: [Agent Plan](https://neon.com/docs/introduction/agent-plan.md) ## Support - **Shared Slack channel:** fastest path for technical questions and urgent issues. - **Neon representative:** account-level requests, custom configuration, escalations. - **Limit increases:** email [agents@neon.tech](mailto:agents@neon.tech) with org ID(s), growth context, and timeline. - **Billing:** raise via Slack or your Neon representative. Credit balances and invoices are in the Neon Console under Billing. - **Community:** [Neon Discord](https://discord.gg/92vNTzKDGp) · [Docs](https://neon.com/docs) · [API reference](https://neon.com/docs/reference/api) ## Repository samples Runnable Management API automation from [neondatabase/neon-for-agent-platforms](https://github.com/neondatabase/neon-for-agent-platforms). - **Quick start:** [README](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/README.md#quick-start) - **Script catalog:** [MANAGEMENT_API_SAMPLES.md](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/MANAGEMENT_API_SAMPLES.md) - **Compound checkpoints:** [COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md) - **Checkpoint orchestration:** [CHECKPOINT_ORCHESTRATION_PATTERN.md](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/CHECKPOINT_ORCHESTRATION_PATTERN.md) - **Doc index:** [SCRIPT-OVERVIEW.md](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/references/SCRIPT-OVERVIEW.md) These scripts use `@neon/sdk` only. Shared [utils.ts](https://github.com/neondatabase/neon-for-agent-platforms/blob/main/skills/neon-postgres-agent-platforms/scripts/utils.ts) builds the client and resolves the default branch; the SDK polls async operations (readiness) for you. For agent-facing Management API tools, see **SDK vs agent tools** above. For SQL access from app code (drivers, pooling, ORMs), use `**neon-postgres`**.