neon-postgres-agent-platforms

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, 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.

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

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/ directory (package.json, npm run …). The **references/** directory keeps markdown guides beside the runnable examples; MANAGEMENT_API_SAMPLES.md is the script catalog and env map. The human Quick start is the root README.

SDK vs agent tools

Your control plane should call @neon/sdk. The sample scripts in this repo do.

The Neon MCP server is a custom agent-facing layer: MCP tool handlers written over @neon/sdk.

Use @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.

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:

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.

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.
• 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).
• 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).
• 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).
• 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 and 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 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 · AI Agents · Project transfer · AI Agent integration

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

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

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).

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. Here, emphasize tenant fleets:

• Persist snapshot and branch IDs per tenant in your ledger. Tie each to non-Neon state via compound checkpoints.
• 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 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 · Backup and restore · 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

Cost, consumption, and entitlements

• Never invent pricing, quotas, or limits. Confirm on Agent Plan and consumption metrics.
• 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).
• 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/ for a routing map (Neon Auth REST vs Postgres roles vs consumption APIs).

Links: Agent Plan · Consumption metrics · Consumption limits · Cost optimization · Plans

Organization and project limit increases

• Current defaults and ceilings are on Agent Plan and AI Agent integration. Do not invent limits.
• For project increase requests, email [e-mail] 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

Support

• Shared Slack channel: fastest path for technical questions and urgent issues.
• Neon representative: account-level requests, custom configuration, escalations.
• Limit increases: email [e-mail] 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 · Docs · API reference

Repository samples

Runnable Management API automation from neondatabase/neon-for-agent-platforms.

• Quick start: README
• Script catalog: MANAGEMENT_API_SAMPLES.md
• Compound checkpoints: COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md
• Checkpoint orchestration: CHECKPOINT_ORCHESTRATION_PATTERN.md
• Doc index: SCRIPT-OVERVIEW.md

These scripts use @neon/sdk only. Shared 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**.