PlanetScale MCPサーバーの使い方 — Claude CodeへのOAuth接続とクエリ安全策
PlanetScaleのMCPサーバーをClaude Codeへ接続する2つの手順と、OAuthスコープ・書き込みクエリの安全策をまとめます。
PlanetScaleのMCPサーバーとは
PlanetScaleのMCPサーバーは、組織・データベース・ブランチ・スキーマ・Insightsデータ、そして支払い方法へホスト型でアクセスできるMCPサーバーです。認証はOAuthで、Claude CodeやCursorなどHTTP接続に対応するMCPクライアントから利用できます。CI・ヘッドレスクライアント向けにはサービストークンでの接続も用意されています。
以前はローカルで動くpscale mcpコマンドが提供されていましたが、この機能はすでに廃止されました。現在はホスト型サーバー(https://mcp.pscale.dev/mcp/planetscale)に一本化されています。Insightsとスキーマ推奨だけを見たい場合は、クエリ実行系のツールを含まないhttps://mcp.pscale.dev/mcp/planetscale-insights-onlyも選べます。
Claude Codeへの接続手順
接続方法は2つあります。PlanetScale公式のプラグインを使う方法と、claude mcp addで直接サーバーを登録する方法です。どちらもOAuth認証は同じ流れになります。
プラグイン経由でインストールする
PlanetScaleはClaude Code向けのプラグインを配布しています。マーケットプレイスを追加してからインストールします。
/plugin marketplace add planetscale/claude-plugin
/plugin install planetscale@planetscale手動でMCPサーバーを追加する
プラグインを使わない場合は、MCPサーバーをコマンドで直接追加できます。まずClaude Codeが利用可能か確認します。
claude --version
claude mcp add --transport http "planetscale" https://mcp.pscale.dev/mcp/planetscaleClaude Codeを起動し、/mcpで接続状態を確認します。認証待ちの状態でサーバーを選んでEnterを押すとブラウザが開き、PlanetScaleへのサインインを求められます。認証が完了すると次のように表示されます。
/mcp❯ /mcp
⎿ Authentication successful. Connected to planetscale.プロジェクトが特定の1つのデータベースだけを対象にするなら、AGENTS.mdに組織名・データベース名・ブランチ名を書いておくと、エージェントが全組織・全データベースを毎回スキャンする手間を省けます。MCPサーバーを自分で作って配布する側の手順はMCPサーバー自作ガイドにまとめています。
認証とスコープ — OAuthでどこまでアクセスできるか
各クライアント(Claude Code、Cursorなど)はPlanetScaleにOAuthアプリケーションとして登録されます。接続時にブラウザへリダイレクトされ、サインインとアクセス許可を行う流れです。
スコープは組織・データベース単位で、アクセスなし・読み取り専用・フルアクセスの3段階から選べます。支払い方法へのアクセスは別枠のスコープで、カード情報の閲覧のみか、Checkoutを開始してカードを更新できるフルアクセスかを選べます。カード更新にはフルアクセスが必須です。
各クエリは実行のたびに短命な一時認証情報を発行し、実行後すぐに削除する設計です。長期間有効な接続文字列をクライアント側で保持しない点が、通常のDB接続との違いになります。権限を見直したいときは、多くのMCPクライアントでMCPサーバーを再認証すればスコープを更新できます。
書き込みクエリの安全策とPostgresの行レベルセキュリティ
意図しないデータ損失を防ぐため、MCPサーバーはいくつかの操作をブロックします。WHERE句のないUPDATE・DELETEは実行できません。TRUNCATEも同様にブロックされます。CREATE・DROP・ALTERなどのDDLは、実行前にLLMへ人間の確認を求めるよう促す仕組みです。
読み取りクエリは、ブランチにレプリカが設定されていれば既定でレプリカへルーティングされ、プライマリの負荷を抑えます。planetscale_execute_read_queryのuse_replicaをfalseにすると、Vitess・Neki・Postgresのいずれでもプライマリへ強制できます。発行されるクエリにはsource=planetscale-mcpというコメントが付き、Insights上で追跡しやすくなっています。
Postgresデータベースの読み取りクエリは、pg_read_all_dataを持つ短命なロールで実行されます。ただし行レベルセキュリティ(RLS)はバイパスしません。SELECT COUNT(*)が0件を返したときなど、結果が0件でRLSが有効なテーブルにアクセスしている場合は、postgres_rls_activeというコードを含むwarnings配列がレスポンスに付きます。0件という結果が「テーブルが空」を意味するとは限らない点に注意が必要です。
PlanetScale Postgresでは、既定でpostgresデータベースに接続します。同じクラスタ内にCREATE DATABASEで作成した別のデータベースがある場合は、planetscale_execute_read_query・planetscale_execute_write_queryのpostgres_database_nameパラメータで対象を切り替えられます。
接続方法の使い分け早見表
Claude Code以外からの接続先も含めると、選択肢は用途によって分かれます。
| 接続方法 | 向いている場面 | 認証方式 |
|---|---|---|
| Claude Codeプラグイン | 向いている場面Claude Codeでの日常的な開発作業 | 認証方式OAuth(ブラウザ認証) |
claude mcp add(手動) | 向いている場面プラグインを使わずCLIで直接登録したい場合 | 認証方式OAuth |
| Claude.ai / Desktopコネクタ | 向いている場面チャット画面からDBを操作したい非CLIユーザー | 認証方式OAuth |
| Claude Managed Agents | 向いている場面platform.claude.comで自律エージェントを常時稼働させる場合 | 認証方式Credential vault経由のMCP OAuth |
| サービストークン | 向いている場面CI・ヘッドレスクライアントでの自動実行 | 認証方式HTTPヘッダーでのトークン送信 |
Claude.aiとClaude Desktopでは、Claude ConnectorsディレクトリからPlanetScaleを検索して追加するか、サーバーURLを手入力するカスタムコネクタとして登録します。カスタムコネクタを使ったリモートMCP接続自体は、Free・Pro・Max・Team・Enterpriseの各プランで利用できますが、Freeプランはカスタムコネクタを1件までしか登録できません。Claude Managed Agentsからつなぐ場合は、platform.claude.comのCredential vaultで「MCP OAuth」を選び、サーバーURLだけを入力してアクセストークン欄は空のまま接続を進めます。
コネクタ経由での接続手順は、対象サービスによって「プラグイン・Connector・手動追加」のどれを選ぶかが分かれます。この違いはPostman MCPサーバーの使い方でも扱っているので、他サービスと比較したいときに参考になります。
使えるツールとできること
PlanetScale MCPサーバーには、日々のデータベース調査・デバッグ・分析向けに整理された25個のツールが用意されています。組織・データベース・ブランチの一覧取得やスキーマ取得、読み書きクエリの実行に加え、クエリのエラーパターン分析やPostgresのサーバーログ取得まで幅広くカバーします。
| カテゴリ | 代表的なツール | できること |
|---|---|---|
| リソース探索 | 代表的なツールplanetscale_list_organizations、planetscale_list_databases、planetscale_get_branch_schema | できること組織・DB・ブランチ・スキーマの一覧と詳細取得 |
| クエリ実行 | 代表的なツールplanetscale_execute_read_query、planetscale_execute_write_query | できること読み取り・書き込みSQLの実行(安全策は前述の通り) |
| パフォーマンス分析 | 代表的なツールplanetscale_get_insights、planetscale_list_query_error_patterns、planetscale_get_postgres_logs | できることクエリ性能・失敗パターン・サーバーログの調査 |
| 請求管理 | 代表的なツールplanetscale_list_invoices、planetscale_update_payment_method | できること請求明細の確認、支払い方法の更新(フルアクセス時) |
ツール自体はオープンソースで、GitHubで公開されています。公式ドキュメントが挙げる利用例には、「本番データベースの一覧とMetal上で動いているものを教えて」「昨日と今日のクエリパターンの違いをInsightsで説明して」といった問い合わせが含まれます。「本番データベースのブランチを一覧にして違いを要約して」「直近1日で最も遅かったクエリを見て、インデックスやクエリの改善案を出して」のように、調査からチューニング提案までを1つの依頼にまとめて投げることもできます。エージェントに自然文で投げかけるだけで、複数のツール呼び出しを組み合わせて答えてくれる設計です。
同じくOAuth接続でエッジDBを扱うTurso MCPサーバーや、ドキュメント型DBを扱うMongoDB MCPサーバーと比べると、PlanetScaleは請求管理やクエリエラー分析まで踏み込んだツール構成が特徴です。
よくあるつまずきと対処
接続やツール実行がうまくいかないときは、公式ドキュメントが次の順で確認を勧めています。
- クライアントを再起動する — インストール直後はMCP設定の再読み込みが必要なことがあります。
- サーバーURLを確認する —
https://mcp.pscale.dev/mcp/planetscaleのホスト型エンドポイントになっているかを見ます。Insights専用サーバーのURLと混同しないようにします。 - MCPサーバーを再認証する — スコープやトークンを変更したあとは、クライアント側で再認証して新しいトークンを取得し直します。
- 組織・データベースへのアクセス権を確認する — 期待するデータが見えないときは、PlanetScaleアカウント側のアクセス権を見直します。
- サービストークンの設定を見直す — OAuthではなくサービストークンで接続している場合は、トークン専用のドキュメントを別途確認する必要があります。
MCPサーバーの接続一覧に反映されるまで時間がかかると感じたときは、Claude Code側のキャッシュ挙動が原因のことがあります。MCP_DISCOVERY_CACHEの挙動を確認すると、表示が遅れる理由が分かります。
まとめ
PlanetScale MCPサーバーは、Claude Codeへプラグインかclaude mcp addのどちらかで接続でき、認証はOAuthに統一されています。書き込みクエリにはWHERE句なし操作のブロックやDDLの確認要求といった安全策があり、Postgresでは行レベルセキュリティも維持されます。CLIでの日常開発ならプラグイン経由、チャットからの利用ならClaude.ai・Desktopのコネクタ、自律エージェントの常時稼働ならClaude Managed Agentsのcredential vaultと、用途に応じて接続経路を選べます。