Neon MCPサーバーで一時ブランチのマイグレーション検証を回す
Neon MCPサーバーで、一時ブランチにマイグレーションを検証してからメインへ適用する手順と、スキーマ比較・スロークエリ分析でパフォーマンスを診断する方法をまとめます。
Neon MCPサーバーは、サーバーレスPostgres「Neon」のAPIをMCPツールとして公開し、自然文でプロジェクト・ブランチ・SQLを操作できるようにするサーバーです。MCP経由でDBに接続する一般的な手順はMCPからデータベースに接続する方法、PostgreSQL専用ツールの比較はPostgreSQL MCPサーバーの使い方で扱っています。この記事が扱うのは、Neonのサーバーレス基盤に固有の機能です。一時ブランチでマイグレーションを検証してからメインブランチへ適用する2段階フロー、スキーマ比較、スロークエリ分析の3つに絞ります。
Neon MCPサーバーのセットアップ方法
Neon MCPサーバーはhttps://mcp.neon.tech/mcpでホストされたリモートサーバーで、Streamable HTTPで接続します。ローカルにインストールするstdio版パッケージ(@neondatabase/mcp-server-neon)は非推奨です。公式ドキュメントはホスト版への移行を明記しています。stdioしか対応しないクライアントを使っている場合だけ、mcp-remoteパッケージでブリッジします。
セットアップ手段は3通りあります。
| 手段 | コマンド | 向く場面 |
|---|---|---|
| CLIによる自動設定 | コマンドnpx neon@latest init | 向く場面エディタ・スキル・プロジェクト連携を一括で済ませたい |
| OAuth認証(推奨) | コマンドclaude mcp add --transport http neon https://mcp.neon.tech/mcp | 向く場面APIキーを管理したくない個人利用 |
| APIキー認証 | コマンド上記コマンドに--headerでトークンを付与 | 向く場面組織のプロジェクトに接続したい、OAuthが使えないリモートエージェント |
Claude Codeでの実際の追加コマンドは次の形です。
claude mcp add --transport http neon https://mcp.neon.tech/mcp
claudeclaudeを起動するとOAuth認証フローが走り、ブラウザでNeonアカウントへのアクセスを許可します。セッション内で/mcpを叩いても同じ認証を開始できます。APIキーで認証したい場合は次のようにヘッダーを付けます。
claude mcp add --transport http neon https://mcp.neon.tech/mcp \
--header "Authorization: Bearer <YOUR_NEON_API_KEY>"OAuth認証は既定で個人アカウント配下のプロジェクトだけを対象にします。組織が持つプロジェクトを操作したい場合、公式READMEはOAuth認証を維持したままプロンプト内でorg_idかproject_idを明示する方法と、APIキー認証に切り替える方法の両方を挙げています。Claude.aiやClaude Desktopから使う場合はNeonが公式Claude connectorとして登録されているため、Settings → Connectors → Browse connectorsからNeonを選ぶだけで、独自のconnector URLを入力せずに追加できます。
マイグレーション・スキーマ以外のカテゴリも1つのサーバーに揃っている
categoryパラメータで絞り込む対象は、マイグレーションやスキーマ関連だけではありません。認証機能を提供するneon_authカテゴリでは、Neonが提供するマネージドのBetter Auth自体をプロビジョニングし、OAuthプロバイダーや信頼済みドメインの追加までを扱えます。data_apiカテゴリは、ブランチ上のデータベースに対してData APIを有効化・無効化するツールです。ドキュメント検索用のdocsカテゴリはOAuth認証なしでも動作し、Neon公式ドキュメントの索引を取得してから該当ページをMarkdownで取得できます。マイグレーション作業中に構文や仕様を確認したいときに、ブラウザを開かずに済みます。
このほかfunctionsカテゴリはNeon Functionsのデプロイ・更新・削除、storageカテゴリはオブジェクトストレージのバケットやオブジェクトの管理、observabilityカテゴリはNeon Functionsのログやオブジェクトストレージのログの参照を担当します。ただしobservabilityはNeon Platform Betaの機能で、対応リージョンがaws-us-east-2とaws-eu-central-1に限られます。対応外リージョンのブランチに対してログ系ツールを呼ぶと、telemetry_not_enabledという理由付きの404が返ります。プロジェクトのリージョンを確認せずにログ調査を依頼すると、ツールが動かない原因がリージョンなのか設定漏れなのか切り分けにくくなる点は覚えておくとよいところです。
一時ブランチでマイグレーションを検証してからメインへ適用する
Neon MCPサーバーの独自価値は、Postgresのブランチ機能を前提にした2段階のマイグレーションフローです。テーブルにカラムを1つ足すような小さな変更でも、いきなり本番相当のブランチへ適用しません。
prepare_database_migration— 渡したマイグレーションを一時ブランチ上に作成し、そこへ適用するcomplete_database_migration— 一時ブランチでの結果を確認したうえで、メインブランチへマージし、一時ブランチを削除する
自然文での指示だけでこの2段階が動きます。公式ガイドが示す例では、Claude Codeに「created_atカラムを追加して」と頼むと、prepare_database_migrationが呼ばれて一時ブランチ(br-silent-cherry-a1eqrl6iのような名前)が作られ、そこでrun_sqlを使って結果を検証します。問題がなければ「適用して」と続けるだけでcomplete_database_migrationが走り、変更が本番相当のブランチへマージされ、一時ブランチは自動的に片付けられます。
一時ブランチをレビューせずに「進めて」と続けて指示すれば1コマンドで完結しますが、run_sqlで一時ブランチ側の状態を確認してからcomplete_database_migrationを呼ぶ運用のほうが安全です。ここが、ブランチを持たない一般的なPostgres MCPサーバーとの最大の違いです。マイグレーションの失敗がメインブランチに触れる前に検出できます。
似た名前のreset_from_parentは別の用途のツールです。これは指定したブランチを親ブランチの現在のHEADへ巻き戻すツールで、分岐後の書き込みを破棄します。マイグレーション検証用の一時ブランチではなく、既存ブランチを親の最新状態にリセットしたいときに使います。子ブランチを持つブランチをリセットする場合はpreserve_under_nameで退避先の名前を指定する必要があります。
スキーマ比較とスロークエリ分析でパフォーマンスを診断する
マイグレーションの前後でスキーマがどう変わったかを見るツールがcompare_database_schemaです。database_nameは必須で、比較対象のbase_branch_idを省略すると親ブランチとの差分になります。過去時点のスキーマと比較したいときはlsnやtimestampをオプションで渡します。
パフォーマンス診断はinspect_databaseが中心です。テーブル・インデックスのサイズ、未使用インデックス、シーケンシャルスキャン、実行中クエリとロック、30秒を超える停滞クエリ、重いクエリと頻出クエリ、キャッシュヒット率とワーキングセット、autovacuumとbloat、レプリケーション状態まで、15種類の読み取り専用診断をひとつのツールで実行できます。CLIのneon inspect dbコマンドと同じチェック内容で、checkパラメータで個別のチェック(table-sizesやunused-indexesなど)を指定することもできます。実行は読み取り専用トランザクション内で行われるため、後述するreadonly=trueのモードでも使えます。一部のチェックにはpg_stat_statementsやneon拡張が必要で、未インストールならツール側がその旨を報告し、CREATE EXTENSIONの提案前に確認を挟みます。
遅いクエリだけをピンポイントで見たいならlist_slow_queriesです。こちらもpg_stat_statements拡張が前提になります。実行計画を確認したいときはexplain_sql_statementを使います。索引調整のような変更を伴うチューニングは、マイグレーションと同じ2段階の考え方でprepare_query_tuningとcomplete_query_tuningが用意されています。一時ブランチ上で最適化を試し、適用するかどうかを選んでから本ブランチへ反映する流れです。
読み取り専用モード・プロジェクト範囲・カテゴリでアクセスを絞る
Neon MCPサーバーはURLのクエリパラメータでアクセス範囲を制御します。設定はリクエストごとに反映されるため、再認証は不要です。
| パラメータ | 効果 |
|---|---|
readonly=true | 効果ブランチ作成・マイグレーション実行・認証設定変更などの書き込み系ツールを無効化する |
projectId=<id> | 効果操作対象を単一プロジェクトに限定し、プロジェクト横断の検索・ナビゲーションを無効化する |
category=<name> | 効果projects / branches / schema / queryingなどカテゴリ単位で有効なツールを絞り込む(繰り返し指定可) |
読み取り専用モードでもSELECTクエリとスキーマ調査は動きます。OAuth認証時は、URLパラメータの代わりに認可画面で読み取り専用スコープを選ぶ方法もあります。ただしget_connection_stringだけは読み取り専用モードでも取得できません。接続文字列には特権ロールのパスワードが含まれるため、読み取り専用モードでは意図的に取得できない設計です。必要ならNeon Console側から直接コピーします。
IP Allowを有効にしているNeonプロジェクトでは、ホスト版MCPサーバーの接続元IP(34.192.103.46と23.22.233.166)をあらかじめ許可リストへ追加しておく必要があります。追加していないと、MCPツール経由の接続がすべて失敗します。
よくあるつまずき
- ローカルstdio版をそのまま使い続けている:
@neondatabase/mcp-server-neonパッケージは非推奨です。新しく設定する場合はホスト版URLを使い、既存のstdio設定はmcp-remote経由のホスト版接続に切り替えます - SSEエンドポイントに接続している:
https://mcp.neon.tech/sseは非推奨で、2026年10月1日以降に廃止され410 Goneを返すようになります。/mcpのStreamable HTTPエンドポイントへ切り替えます - 組織のプロジェクトに接続できない: OAuth認証は既定で個人アカウント配下のプロジェクトしか見えません。プロンプトに
org_idかproject_idを明示するか、APIキー認証に切り替えます readonly=trueにしても接続文字列だけ取れない: 意図した挙動です。読み取り専用モードではget_connection_stringが常に無効化されるため、Neon Consoleから直接取得しますlist_slow_queriesや一部のinspect_databaseチェックが空を返す:pg_stat_statements拡張が有効化されていないと動きません。事前に拡張を有効にしておきます
まとめ
Neon MCPサーバーの独自価値は、Postgresのブランチ機能を前提にした一時ブランチ経由のマイグレーション検証と、compare_database_schemaによるスキーマ比較、inspect_databaseによるまとまった診断です。ローカルstdio版は非推奨なので、これから設定するならhttps://mcp.neon.tech/mcpをStreamable HTTPで使います。組織のプロジェクトを扱うならAPIキー認証、個人アカウントで完結するならOAuth認証を選び、本番データベースには公式が推奨しない前提で、readonly=trueやカテゴリ制限を使って操作範囲を絞っておくのが安全な既定運用です。汎用的なMCP経由のDB接続はMCPからデータベースに接続する方法、Postgres固有の索引提案・ヘルスチェックとの比較はPostgreSQL MCPサーバーの使い方、Claude Code側のclaude mcp addの構文全般はClaude Code MCP設定ガイドで扱っています。