neon-postgres-agent-platforms

Neon AI Agent Program

**neon-postgres** の補完スキルです（先にインストールしてください）。このスキルでは、Neon Agent Program のフリート規模のコントロールプレーンを扱います。デュアル組織構成、プロジェクトの移管、テナントごとのプロビジョニング、複合チェックポイント、利用量、商用条件、および @neon/tools を介してエージェントに Management API アクセスを許可するタイミングについて説明します。

接続文字列、ドライバー、ORM、ブランチ作成のチュートリアル、アプリでの Auth、Data API、Neon のホステッド MCP については、**neon-postgres** と Neon のドキュメントを参照してください。

対象範囲

一般的な Neon の利用には **neon-postgres** を使用してください。次の内容を含む質問には、このスキルを使用してください。

• デュアル組織の費用と API キー（個人、組織、プロジェクトスコープ）
• コントロールプレーン向けの @neon/sdk と、エージェント向けの Management API アクセス用の @neon/tools
• テナントごとのプロジェクトのプロビジョニングと移管
• フリート全体のスナップショット／復元のオーケストレーションとハウスキーピング
• 複合チェックポイント
• 従量制フリートの利用量ポーリング
• Agent Plan の商用条件（数値を創作せず、リンクを提示）
• パートナーサポートの窓口

スキルをインストールする

npx skills add neondatabase/agent-skills -s neon-postgres

アシスタント：インストール後にできること

**neon-postgres** と このスキルを読み込むと、プラットフォームレベルの Neon 作業に十分なコンテキストを得られます。デュアル組織構成、新しいテナント向けのプロジェクトのプロビジョニング、複合チェックポイント、組織全体の利用量ポーリング、移管／アップグレードのフローに対応でき、ユーザーが長いドキュメントを貼り付ける必要はありません。

実行可能なサンプルの場所： TypeScript のサンプルは、このスキルの scripts/ ディレクトリから実行できます（package.json、npm run …）。**references/** ディレクトリには、実行可能なサンプルとあわせて Markdown ガイドが格納されています。 MANAGEMENT_API_SAMPLES.md はスクリプトカタログと環境変数の一覧です。人間向けの クイックスタートは、ルートの README にあります。

SDK とエージェントツールの違い

コントロールプレーンからは @neon/sdk を呼び出してください。このリポジトリのサンプルスクリプトでも使用しています。

Neon MCP サーバー は、エージェント向けにカスタマイズされたレイヤーです。@neon/sdk を使って記述された MCP ツールハンドラーで構成されています。

プラットフォーム上のエージェントに、ハンドラーを自作することなく Neon の管理機能へ直接アクセスさせたい場合は、@neon/tools を使用してください。選択した SDK メソッドの生成ラッパーをエージェントツールとして公開し、MCP、Eve、Mastra 用のアダプターを備えています。

次の公開クライアントメソッドはツールではありません。projects.create、branches.create、operations.waitFor、postgres.roles.password、storage.objects.get。コンピュートをアタッチして接続文字列を返す作成処理には、projects.createAndConnect と branches.createWithCompute を使用してください。書き込みツールではすでに待機処理が行われます。生成されたスキーマは厳密です。新しく追加された API フィールドは、@neon/tools をアップグレードするか、@neon/sdk を直接呼び出すまで拒否されます。

セレクターには SDK のパス（projects.list）を指定します。モデル向けの ID（projects.list → list_projects）を取得するには publishedId を呼び出してください。toolIds にはすべてのセレクターが一覧表示されます。MCP 2.x では @neon/tools/mcp を、MCP 1.x では @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 には関数を指定できるため、リクエストごとに短期間有効なトークンを更新できます。すでにクライアントを認証済みのリモート MCP サーバーでは、インスタンスの作成時に apiKey を省略できます。その場合、registerNeonTools が authInfo.token を送信します。

MCP のアノテーションは参考情報です。@neon/tools/mcp を使用するホストは、MCP _meta の neon/requiresApproval を読み取り、実行前に独自の承認ポリシーを適用する必要があります。Eve および Mastra のアダプターでは、このフラグをそれぞれ Eve の approval フックと Mastra の requireApproval にマッピングします。読み取り専用でない操作はすべて承認が必要としてマークされ、接続資格情報を返す読み取り操作も同様にマークされます。

各エージェントに必要なメソッドだけを選択してください。テナントスコープのエージェントでは、パスの project_id を注入して、パスパラメーターにその値を取るツールでモデルが別のプロジェクトを選択できないようにします。

const tools = createNeonTools({
  apiKey,
  tools: ["projects.get", "branches.createWithCompute"] as const,
  inject: {
    projectId: tenantProjectId,
    omitFromSchema: true,
  },
});

inject.projectId が設定するのは URL パスの project_id のみです。同じ名前のクエリフィールドやボディフィールドは非表示にならず、プロジェクトのパスがないツール（たとえば projects.list）も制限されません。エージェントに組織の残りの情報を見せてはならない場合は、プロジェクトスコープの API キーと併用してください。

API の全内容については、@neon/tools README を参照してください。

注意点

エージェントが誤解しやすい、ひと目では分かりにくい事実：

• チェックポイントは複合レコードです。 テナントのチェックポイントには、ソースのリビジョン、Neon のスナップショット／ブランチ、シークレット／環境変数のバージョン、デプロイ URL、エージェントのメタデータが含まれます。「チェックポイント」を単なる「Neon ブランチ」と同一視しないでください。複合チェックポイントのドキュメントを参照してください。
• 組織間の移管には個人用 API キーが必要です（組織キーは同一組織内でのみ機能します）。Neon で GitHub または Vercel のインテグレーションが設定されているプロジェクトは移管できません。API は 422 を返します（プロジェクトの移管）。
• 確定済みスナップショットから復元した後は、アクティブなブランチ ID が変わります。再接続する前に、操作が完了するまでポーリングしてください。ストレージ料金を避けるため、孤立した (old) ブランチを削除してください。
• 請求に沿った使用量： 古い使用量エンドポイントよりも、GET /api/v2/consumption_history/v2/projects を優先してください。従来のアカウント単位のエンドポイントは廃止されています。v2 のプロジェクト単位のエンドポイントを使用してください（従来の使用量ガイド）。
• V2 の metrics パラメーター値（実装者向け）：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（使用量メトリクス）。
• スナップショットスケジュールは Agent Plan では提供されません。パートナーはスナップショット API と独自のスケジューラーを使って実装します。
• 料金と上限： 金額や上限を決して作り上げないでください。最新の neon.com ドキュメントで確認してください。

Agent Plan と 2 つの組織

パートナーは2 つの Neon 組織を運営します。

組織	役割
無料提供の組織	プログラムの規則に沿った無料プランのエンドユーザー
有料組織	Agent Plan に基づき従量課金される顧客

主なポイント：

• 料金、クレジット、プロジェクト上限は、最新の Agent Plan と neon.com/agents に記載された情報のみを参照してください。数値を作り上げないでください。
• 組織 API キー： 1 つの組織内での自動化（プロジェクトの作成、クォータの設定）。
• 個人用 API キー： 顧客のプラン変更に伴って組織間でプロジェクトを移管し、その後、新しいプランに合わせてクォータを PATCH する際に必要です。
• プロジェクトスコープの API キー： 1 つのプロジェクトのみに対するメンバーレベルのアクセスです。組織キーよりも権限が限定されており、組織内の他のプロジェクトに触れてはならないテナントごとのランタイムや自動化に役立ちます。組織全体で新しいプロジェクトを作成することはできません。プロジェクトが組織外に移管されると無効になります。

リンク： Agent Plan · AI エージェント · プロジェクトの移管 · AI エージェントのインテグレーション

HIPAA

• Agent Plan には HIPAA が含まれており、追加料金はかかりません。 ただし、パートナーは引き続き、Neon が公開している HIPAA プログラム（ワークフロー、契約、構成）に従う必要があります。
• アクセスを取得するか手続きを開始するには、Neon の主担当者にお問い合わせください。
• このスキルは法的助言ではありません。

リンク：Neon の HIPAA

フリート構成：テナントごとにプロジェクトを作成

• テナントごとにプロジェクトを作成する方式は、Neon が文書化しているフリートパターンです。プロビジョニングの対象となる各テナント（エンドユーザー、顧客向けアプリ、またはエージェントのワークロード）に、それぞれ専用のNeon プロジェクトを割り当てます。このプロジェクトが、ブランチ、データベース、ロール、コンピュートの分離境界となります。スキーマで分割するだけの共有 Postgres クラスターとは異なります。
• 分離と課金：プロジェクトを分けることで、テナント間のデータとリソースを完全に分離し、プロジェクト単位で使用量の上限と課金を明確に管理できます（このスキルの別の箇所で説明している Agent Plan の計測方法にも対応します）。また、Neon Management API と Console の構成（プロジェクト単位の作成、クォータ、ライフサイクルに関する呼び出し）にも合致します。

ステージングと本番環境

• 各テナントのプロジェクトでは、ステージングと本番環境（および一時的なプレビュー）を、プロジェクト内のブランチとスナップショットに基づくライフサイクルとして扱います。フリートのオーケストレーションには、別のプロジェクトを既定で作成するのではなく、以下のスナップショットとデータベースのバージョン管理およびサンドボックスとプレビュー用データベースを使用します。
• エージェントやアプリのビルダー：****自社プラットフォームの環境（たとえば、ビルダーやコントロールプレーンのホスティング方法）と、各テナントのステージング用および本番用ブランチを分けて考えてください。台帳や自動化において、「自社の本番サービス」と「テナントの本番ブランチ」を混同しないようにしてください。
• 組み込み型製品の中には、信頼、キー、課金の境界を設けるため、エンドカスタマーの本番環境と開発環境の Neon アセットを別々の組織に分けるものもあります。このケースに該当する場合は、次の**ブランチを越えた分離（プロジェクトと組織に関する例外的なケース）**を参照してください。

リンク： AI エージェント統合ガイド

ブランチを超える分離（プロジェクトおよび組織に関するエッジケース）

テナントのスコープや信頼要件が、Fleet 形式の本番環境とステージング環境におけるブランチおよびスナップショット優先の運用を超える場合は、プロジェクト単位または組織単位で分割します。組み込み型の製品では、エンドカスタマーごとの本番環境と開発環境のデータベースを、ブランチだけでなく別々の Neon 組織に分けて分離できます。各組織内でブランチを管理しながら、課金、組織 API キー、コンソールの境界をより厳密にできます。

プロジェクト単位の分離（テナントまたはワークロードごとに複数のプロジェクトを使用）：

• 接続文字列またはロールが侵害された場合の影響範囲をより小さくできます。漏えいが無関係なワークロードに波及しないようにします。
• 自動化や所有権が同じ Postgres 内で衝突する場合に、運用ライフサイクルを分離します（たとえば、本番データと、破棄可能な分析用または移行用のサンドボックス）。
• 移行権限または管理者権限が競合するチームや自動化を分離します。
• 単一のデータベースで複数のワークロードを混在させてはならない、厳格なコンプライアンス要件やデータ混在ルールに対応します。

プロジェクトを追加するたびにフリートの管理対象が増えます。API キー、消費量の記録、保守作業が増え、運用コストも高くなります。上記の境界条件に明確に該当しない限り、テナントごとにプロジェクトを設ける方法をデフォルトにしてください。

組織単位の分離（スポンサー提供の無料プランと有料プランの分離を超えて）：

• Agent Plan and two organizationsで説明する2 組織の構成は、商用上の分割（無料プランのユーザーと有料顧客の分離）です。このパターンは、組み込み型製品の分割と併用できます。たとえば、エンドカスタマーごとに本番用組織と開発用組織を設けることで、プレイグラウンド用データベースが出荷済みの本番環境と組織スコープを共有しないようにできます。どの組織がどの環境とプランを所有するか、明確な内部対応表を維持してください。
• これとは別に、契約上の要件（エンタープライズ向けの「顧客専用組織」）、リセラーまたは MSP モデル、地域的または法的な分離のために、パートナーが追加の Neon 組織やアカウントを必要とする場合があります。製品のデフォルトや制限は最新のドキュメントで確認し、上限を独自に設定しないでください。
• 組織 API キーのスコープは単一の組織です。 Gotchasにあるように、組織間の移動には個人用 API キーとプロジェクトの移転を使用します。組織キーで組織をまたいだ操作ができると想定しないでください。プロジェクトスコープのキーは、さらに単一のプロジェクトに制限されます（API キー）。

組み込み時の衛生管理：

• プラットフォームの各サービス（コントロールプレーン、テナントのランタイム、課金または消費量のジョブ）に最小権限のキーを割り当てます。適切でないレイヤーで、本番用キーをサンドボックスに使い回さないでください。
• エンドカスタマーごとの本番環境と開発環境が別々の Neon 組織にある場合、自動化のスコープを組織ごとに設定します（通常は組織ごとに組織 API キーを 1 つ使用します）。また、ジョブや復元処理が正しい側を対象にするよう、org_idをproject_id／branch_idとともに保存します。
• 復元、移転、監査の一貫性を保てるよう、台帳（project_id、branch_id、組織、チェックポイントのメタデータ）を選択した分離レイヤーに合わせて管理します。

スナップショットとデータベースのバージョン管理

スナップショットのセマンティクス、アクティブブランチのパターン、復元のチュートリアルについては、 **neon-postgres** と AI database versioning を参照してください。 ここでは、テナントのフリートに重点を置きます。

• スナップショット ID とブランチ ID をテナントごとに台帳へ保存します。それぞれを 複合チェックポイント を使って Neon 以外の状態にひも付けます。
• 復元の確定後はブランチ ID が変わり、孤立した (old) ブランチが 蓄積します。クリーンアップを自動化し、保存済みの ID を更新します。
• テナントアプリを再接続する前に、操作が完了するまでポーリングします。
• 製品の仕様（プランごとのスナップショット数、ベータ版の料金適用日）は変更されます。 Agent Plan のドキュメントで確認してください。

プラットフォームレベルの一般的なチェックポイントのトリガー：

• テナント向けに生成されたスキーマ変更を反映する前
• テナントのデータベースを変更するエージェントの実行の開始時または終了時
• 破壊的なマイグレーションや、顧客に見える復元操作の前

リンク： AI database versioning · バックアップと復元 · チェックポイントとしてのスナップショットのデモ

サンドボックスとプレビュー用データベース

パートナーが、生成されたアプリ向けにテナントごとのプレビュー用またはサンドボックス用データベースを必要とする場合に使用してください。（単一のアプリでの「ブランチを作成する方法」は **neon-postgres** を参照してください。）

• Management API 経由でプレビューを作成する際は、顧客／エージェントの実行ごとに project_id / branch_id を追跡します。
• ブランチ数とストレージ使用量はフリートの規模に応じて増加します。上限を監視し、アイドル状態のプレビューをガベージコレクションします。
• プレビュー用コンピュートの suspend_timeout_seconds を短くすると、コストを削減できます。
• ブランチ／スナップショットのライフサイクルを、シークレットのローテーションやデプロイ URL と複合チェックポイントを使って組み合わせます。

リンク： AI エージェント統合ガイド

コスト、使用量、利用資格

• 料金、クォータ、制限を決して捏造しないでください。Agent Plan と 使用量メトリクス で確認してください。
• 請求に対応するフィールドには GET /api/v2/consumption_history/v2/projects を使用します。 レガシーエンドポイントとは異なります。レガシーのアカウントレベルのエンドポイントは廃止されています。 代わりに、プロジェクトごとの v2 メトリクスを使用してください （レガシーガイド）。
• V2 の metrics クエリ文字列は正確に次のとおりです：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。
• 使用量は約 15 分ごとにポーリングします。ポーリングによって、サスペンド中のコンピュートが起動することはありません。
• scripts/ の auth-users.ts meta を実行し、ルーティングマップ（Neon Auth REST、Postgres ロール、使用量 API の区分）を確認します。

リンク： Agent Plan · 使用量メトリクス · 使用量の上限 · コスト最適化 · プラン

組織とプロジェクトの上限引き上げ

• 現在のデフォルトと上限は、 Agent Plan と AI Agent integration に記載されています。 上限を捏造しないでください。
• プロジェクトの上限引き上げを申請する場合は、組織 ID、成長の背景、 希望する時期を記載して [email protected] にメールしてください。利用可能であれば、共有 Slack にも連絡してください。

共同マーケティング

• 共同マーケティングは、Agent Plan に含まれる特典です。
• 利用可能な内容：共同ブログ記事、SNS でのプロモーション、ハッカソンのスポンサーシップ、事例紹介、ランディングページへの掲載。
• 取り組んでいる内容を添えて、共有 Slack または Neon の担当者にご連絡ください。

リンク：Agent Plan

サポート

• 共有 Slack チャンネル： 技術的な質問や緊急の問題に最も迅速に対応できます。
• Neon の担当者： アカウントに関する依頼、カスタム設定、エスカレーションに対応します。
• 上限の引き上げ： 組織 ID、成長の状況、希望する時期を添えて、 [email protected] までメールでご連絡ください。
• 請求： Slack または Neon の担当者を通じてお問い合わせください。クレジット残高と請求書は、Neon Console の「Billing」から確認できます。
• コミュニティ： Neon Discord · ドキュメント · API リファレンス

リポジトリのサンプル

neondatabase/neon-for-agent-platforms の実行可能な Management API 自動化サンプルです。

• クイックスタート： README
• スクリプトカタログ： MANAGEMENT_API_SAMPLES.md
• 複合チェックポイント： COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md
• チェックポイントのオーケストレーション： CHECKPOINT_ORCHESTRATION_PATTERN.md
• ドキュメントのインデックス： SCRIPT-OVERVIEW.md

これらのスクリプトで使用するのは @neon/sdk のみです。共有の utils.ts がクライアントを構築し、デフォルトブランチを解決します。SDK が非同期操作（準備完了）のポーリングを行います。エージェント向けの Management API ツールについては、上記の SDK vs agent tools をご覧ください。アプリコードから SQL にアクセスする場合（ドライバー、コネクションプーリング、ORM）は、**neon-postgres** を使用してください。