Neon MCPサーバーで一時ブランチのマイグレーション検証を回す

Neon MCPサーバーは、サーバーレスPostgres「Neon」のAPIをMCPツールとして公開し、自然文でプロジェクト・ブランチ・SQLを操作できるようにするサーバーです。MCP経由でDBに接続する一般的な手順はMCPからデータベースに接続する方法にあります。PostgreSQL専用ツールの比較はPostgreSQL MCPサーバーの使い方です。この記事はNeonのサーバーレス基盤に固有の機能に絞ります。一時ブランチでのマイグレーション検証、スキーマ比較、スロークエリ分析、そしてアクセス範囲の絞り込みです。

Neon MCPサーバーのセットアップ方法

Neon MCPサーバーはhttps://mcp.neon.tech/mcpでホストされたリモートサーバーで、Streamable HTTPで接続します。ローカルにインストールするstdio版パッケージ(@neondatabase/mcp-server-neon)は非推奨で、公式ドキュメントはホスト版への移行を求めています。stdioしか対応しないクライアントでは、mcp-remoteパッケージでホスト版へブリッジします。

セットアップ手段は次の4通りです。

npx neon@latest initを使うと、MCPサーバーに加えてエージェント用スキルとNeonプロジェクトのリンクまで一括で済みます。Neonのガイドはこの方法を推奨の入口にしています。

Claude Codeで手動追加する場合のコマンドは次の形です。

claude mcp add --transport http neon https://mcp.neon.tech/mcp
claude

claudeを起動するとOAuth認証フローが走り、ブラウザでNeonアカウントへのアクセスを許可します。セッション内で/mcpを実行しても同じ認証を始められます。APIキーで認証するなら、ヘッダーを付けます。

claude mcp add --transport http neon https://mcp.neon.tech/mcp \
  --header "Authorization: Bearer <YOUR_NEON_API_KEY>"

v2.1.289のclaude mcp add --helpでは、--transportの選択肢はstdio・sse・httpで、省略時はstdioになります。--transport httpを付け忘れるとURLがコマンド名として扱われます。--scopeの既定はlocalで、チームで共有する設定ならprojectを選びます。

Claude.aiやClaude Desktopから使う場合、Neonは公式のClaude connectorとして登録されています。Settings → Connectors(画面によってはCustomize → Connectors)を開き、Browse connectorsでNeonを選びます。独自のconnector URLを入力せずに追加できます。

組織のプロジェクトを操作するときの認証の分かれ目

OAuth認証は、既定では個人アカウント配下のプロジェクトだけを対象にします。組織が持つプロジェクトの扱いは、Neonの2つの資料で説明が少し違います。Claude Code向けガイドは「組織のアカウントに接続するにはAPIキーで認証する」と書いています。GitHubのREADMEは、OAuthのままプロンプトにorg_idかproject_idを明示する方法も挙げています。

一時ブランチでマイグレーションを検証してからメインへ適用する

Neon MCPサーバーの独自価値は、Postgresのブランチ機能を前提にした2段階のマイグレーションフローです。カラムを1つ足すだけの変更でも、いきなり本番相当のブランチへは適用しません。

自然文の指示だけでこの流れが動きます。Neonのガイドの例では、Claude Codeに「created_atカラムを追加して」と頼みます。するとprepare_database_migrationが呼ばれ、br-silent-cherry-a1eqrl6iのような名前の一時ブランチができ、「本番ブランチへコミットしますか」と尋ねられます。「やって」と返すとcomplete_database_migrationが走り、一時ブランチは片付けられます。

人間の判断を挟めるのは、検証後に承認を求める1点です。一時ブランチを見ずに続けて指示すれば、1回の依頼で完結します。ただ、run_sqlで一時ブランチ側の状態を見てから進めてこそ、このフローの意味が出ます。ブランチを持たない一般的なPostgres MCPサーバーとの最大の違いはここで、失敗がメインブランチに触れる前に見つかります。

似た名前のreset_from_parentは別の用途のツールです。指定したブランチを親ブランチの現在のHEADへ巻き戻し、分岐後の書き込みを破棄します。子ブランチを持つブランチをリセットするときは、preserve_under_nameで退避先の名前を指定します。

スキーマ比較とスロークエリ分析でパフォーマンスを診断する

マイグレーションの前後でスキーマがどう変わったかを見るツールがcompare_database_schemaです。database_nameは必須で、比較対象のbase_branch_idを省略すると親ブランチとの差分になります。過去時点のスキーマと比べたいときは、lsnやtimestampをオプションで渡します。

パフォーマンス診断の中心はinspect_databaseです。15種類の読み取り専用診断を、ひとつのツールで実行できます。対象は、テーブル・インデックスのサイズ、未使用インデックス、シーケンシャルスキャン、実行中クエリとロック、重いクエリと頻出クエリ、キャッシュヒット率、autovacuumとbloat、レプリケーション状態です。30秒を超えて動き続けているクエリはstalled-queriesチェックが拾います。CLIのneon inspect dbと同じ内容で、checkパラメータにtable-sizesやunused-indexesを渡すと個別に走ります。database_nameを省くとブランチ上の全データベースが対象です。

実行は読み取り専用トランザクション内で行われるため、読み取り専用モードでも使えます。READMEによると、4つのチェックはpg_stat_statementsかneon拡張を必要とします。未導入ならツールがその旨を伝え、CREATE EXTENSIONを提案する前に確認を挟みます。

遅いクエリだけを見たいならlist_slow_queriesで、こちらもpg_stat_statementsが前提です。実行計画はexplain_sql_statementで見ます。インデックス追加のような変更を伴うチューニングには、マイグレーションと同じ2段階のprepare_query_tuningとcomplete_query_tuningがあります。一時ブランチで最適化を試し、適用か破棄かを選んでから本ブランチへ反映します。

読み取り専用モード・プロジェクト範囲・カテゴリでアクセスを絞る

アクセス範囲はMCPサーバーのURLにクエリパラメータを付けて制御します。

Claude Codeで付けるときは、URLを引用符で囲みます。&をそのまま書くとシェルが解釈してしまうためです。

claude mcp add --transport http neon \
  "https://mcp.neon.tech/mcp?readonly=true&projectId=<your-project-id>"

絞り込みの効果は、認証方式によって反映のされ方が変わります。READMEの説明を並べると次のとおりです。

URLパラメータの効き方は、/api/list-toolsで実際に確かめられます。認証なしで呼べるエンドポイントで、設定ごとに有効なツールの一覧がJSONで返ります。

curl -s "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

同じエンドポイントが返すツール数を、設定を変えて並べると絞り込みの粒度が分かります。

categoryで絞っても、search・fetch・send_feedbackの3本はカテゴリに属さないため残ります。projectIdを付けると、プロジェクトをまたぐlist_projects・list_organizations・list_regions・search・fetchが消えます。読み取り専用でもrun_sqlは残りますが、読み取りクエリだけが通る扱いです。マイグレーションとチューニングのprepare_系・complete_系の4本は書き込み系なので、読み取り専用の一覧には出ません。

読み取り専用モードで取得できないのはget_connection_stringも同じです。接続文字列には特権ロールのパスワードが含まれるため、意図的に外されています。必要なときはNeon Consoleから直接コピーします。

12カテゴリの中身と、地域で変わるツール

categoryで指定できるカテゴリは、公式ドキュメントでは12あります。マイグレーションとスキーマ以外にも、用途の広いものが揃っています。

docsカテゴリは、マイグレーション中に構文を調べたいときにブラウザを開かずに済みます。

observabilityはNeon Platform Betaに属し、対応リージョンの書き方が資料によって違います。公式ドキュメントのページは4つを挙げます。aws-us-east-2・aws-us-east-1・aws-eu-central-1・aws-ap-southeast-1です。READMEはaws-us-east-2のみとしています。ログにアクセスできないブランチでログ系ツールを呼ぶと、telemetry_not_enabledという理由付きの404が返ります。対応リージョンのプロジェクトかどうかを、まず確かめます。

利用状況の送信とネットワーク側の前提

READMEのTelemetry節によると、ホスト版のNeon MCPサーバーはプロダクト分析とエラー報告を収集します。認証済みアカウントで接続すると、Neonアカウントのid・名前・メールアドレスを含むidentifyイベントが送られます。ツール呼び出しごとのイベントに入るのは、ツール名・認証方式・クライアントで、ツールの引数やクエリ結果は含まれません。送信先はtrack.neon.techです。予期しないサーバーエラーは、スタックトレースとリクエストの文脈つきでSentryに報告されます。

READMEが挙げる無効化の手段は、自分でサーバーを動かす場合の環境変数NEON_MCP_DISABLE_ANALYTICS=1だけです。この変数でもSentryへのエラー報告は止まりません。社内の持ち出し規則で分析の送信が問題になる環境かどうかを、接続前に見ておく項目になります。

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へ切り替えます。SSEはAPIキー認証に対応していません
• claude mcp addでURLがコマンドとして扱われる: --transport httpが抜けています。省略時の既定はstdioです
• &を含むURLを追加すると途中で切れる: シェルが&以降を別のコマンドとして解釈しています。URL全体を引用符で囲みます
• 組織のプロジェクトが一覧に出ない: OAuthの既定は個人アカウント配下だけです。プロンプトにorg_idかproject_idを明示するか、APIキー認証に切り替えます
• list_slow_queriesや一部のinspect_databaseチェックが拡張未導入の旨を返す: pg_stat_statements(またはneon)拡張が前提です。先に拡張を有効にします

まとめ

Neon MCPサーバーを使う価値は、一時ブランチ経由のマイグレーション検証にあります。ただし公式が本番接続を推奨していないため、接続先は開発用のプロジェクトにして、readonly=trueやprojectIdで書き込みと範囲を絞ってから始める構成が堅実です。claude mcp addの構文全般はClaude Code MCP設定ガイドにあります。