PlanetScale MCPサーバーの使い方 — Claude Codeへの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 Code向けプラグインを使う方法と、claude mcp addで直接登録する方法です。どちらもOAuth認証の流れは同じです。

プラグインでインストールする

マーケットプレイスを追加してから、プラグインをインストールします。

/plugin marketplace add planetscale/claude-plugin
/plugin install planetscale@planetscale

手動でMCPサーバーを追加する

登録コマンドをv2.1.289で空のディレクトリに実行すると、--scope projectを付けた場合にそのディレクトリへ.mcp.jsonが作られます。

mkdir ps-demo && cd ps-demo
claude mcp add --scope project --transport http planetscale \
  https://mcp.pscale.dev/mcp/planetscale

Added HTTP MCP server planetscale with URL: https://mcp.pscale.dev/mcp/planetscale to project config
File modified: .../ps-demo/.mcp.json

生成される.mcp.jsonは次の内容です。--scopeの既定値はlocalで、projectを指定するとチームで共有できるファイルに書かれます。

{
  "mcpServers": {
    "planetscale": {
      "type": "http",
      "url": "https://mcp.pscale.dev/mcp/planetscale"
    }
  }
}

プロジェクトスコープのサーバーは、初回に承認するまでPending approvalの扱いになります。リポジトリをcloneしただけでは有効にならない仕組みです。

プロジェクトが特定の1つのデータベースだけを対象にするなら、AGENTS.mdに組織名・データベース名・ブランチ名を書いておきます。MCPサーバーが全組織・全データベースをスキャンする手間を省けます。MCPサーバーを自分で作って配布する側の手順はMCPサーバー自作ガイドにあります。

OAuthのスコープでどこまで見せるか

各クライアント(Claude Code、Cursorなど)は、PlanetScaleにOAuthアプリケーションとして登録されます。接続時にブラウザへリダイレクトされ、サインインとアクセス許可を行う流れです。

スコープは組織またはデータベース単位で、アクセスなし・読み取り専用・フルアクセスの3段階から選べます。支払い方法は別枠で、カードの閲覧だけか、Checkoutを開始してカードを更新できるフルアクセスかを選びます。カード更新にはフルアクセスが必須です。

各クエリは実行のたびに短命な一時認証情報を発行し、実行後すぐに削除します。長期間有効な接続文字列をクライアント側に置かない点が、通常のDB接続との違いです。権限を変えたいときは、多くのMCPクライアントでMCPサーバーを再認証すれば更新できます。

CI・ヘッドレスで使うサービストークンの権限

ブラウザでサインインできない環境では、サービストークンをBearerトークンとして送ります。送り先は通常のサーバーURLで、insights-onlyサーバーにも同じヘッダーが使えます。

手順は次のとおりです。

1. 組織設定でサービストークンを作る
2. pscale_tkn_で始まるtoken値をコピーする(トークンIDではない)
3. MCPツールに使わせたい権限だけをトークンに付ける
4. 実行環境のPLANETSCALE_API_TOKENにtoken値を入れる
5. Authorization: Bearer pscale_tkn_...として送る

Bearer <id>:<secret>の形は拒否されます。送るのはtoken値だけです。また、Claude.ai・Claude for desktop・Claude Managed Agents・Notionの4つはOAuthのみで、サービストークンのヘッダーを受け付けません。

権限の付け方は3段階

OAuthのように画面で選べないため、権限はトークン側で組みます。MCPサーバーはトークンの権限でPlanetScale APIを呼ぶので、足りない権限のツールは失敗します。

読み取り専用のつもりでconnect_production_branchを付けないよう注意が必要です。この権限は本番で書き込み用の認証情報を作れるため、読み取りの代わりにはなりません。read_databaseはメタデータ(名前・状態・既定ブランチ)を返すだけで、MySQLやPostgresには接続しません。クエリ実行にはconnect_*系の権限が別に要ります。

請求まわりの権限も独立しています。請求明細ツールには組織のread_invoices、カードの閲覧にはread_payment_method、Checkout開始にはwrite_payment_methodが必要です。

Claude Codeにトークンを渡すときの落とし穴

PlanetScaleのサービストークン手順は、Claude Code向けに--header "Authorization: Bearer ${PLANETSCALE_API_TOKEN}"付きのclaude mcp addを案内しています。この書き方はシェルが先に変数を展開するので、トークンの実値が設定ファイルに書き込まれます。

v2.1.289でダミーの値を使い、プロジェクトスコープに追加すると次のようになります。

claude mcp add --scope project --transport http planetscale-insights \
  https://mcp.pscale.dev/mcp/planetscale-insights-only \
  -H "Authorization: Bearer TOKEN"

コマンドの出力ではAuthorizationが[REDACTED]に伏せられます。一方、できあがる.mcp.jsonには値がそのまま入ります。

"planetscale-insights": {
  "type": "http",
  "url": "https://mcp.pscale.dev/mcp/planetscale-insights-only",
  "headers": {
    "Authorization": "Bearer TOKEN"
  }
}

画面の伏せ字はログ向けの表示で、ファイルの中身までは守りません。チームで共有する.mcp.jsonにトークンを書かないなら、Claude Codeの環境変数展開を使い、"Authorization": "Bearer ${PLANETSCALE_API_TOKEN}"と書いたまま保存します。${VAR}と${VAR:-default}の2つの形が使えます。展開された値は、起動時の環境変数から読まれます。

書き込みクエリの安全策と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)はバイパスしません。結果が0件でRLSが有効なテーブルに触れていた場合、レスポンスにpostgres_rls_activeというコードを含むwarnings配列が付きます。0件が「テーブルが空」を意味するとは限りません。

PlanetScale Postgresでは既定でpostgresデータベースに接続します。同じクラスタにCREATE DATABASEで作った別のデータベースがあるなら、読み取り・書き込みの両ツールのpostgres_database_nameで対象を切り替えます。

25個のツールと、依頼の出し方

ツールは日々のデータベース調査・デバッグ・分析向けに25個あります。ツール自体はGitHubで公開されています。

依頼は、ツール名ではなく調べたいことを自然文で書きます。たとえば次のような依頼を、複数のツール呼び出しにまとめて実行できます。

• 「本番データベースのブランチを一覧にして、違いを要約して」
• 「直近1日で最も遅かったクエリを見て、インデックスやクエリの改善案を出して」
• 「どのルートタグがデータベース時間を一番使っている?」

最後の問いに答えるのが、クエリタグ系のツールです。アプリ側でルートやジョブ名のタグを付けていれば、時間・レイテンシ・読み取り行数・エラーをその単位で集計できます。

OAuth接続でTurso Cloudを扱うTurso MCPサーバーや、Atlasのプラグイン経由でドキュメント型DBを扱うMongoDB MCPサーバーと比べると、PlanetScaleは請求管理やクエリエラー分析まで踏み込んだ構成です。コネクタ経由で入れるときに「プラグイン・Connector・手動追加」のどれを選ぶかは、Postman MCPサーバーの使い方でも扱っています。

Claude.aiとDesktopのコネクタ、Managed Agents

Claude.aiとClaude Desktopでは、Claude ConnectorsディレクトリでPlanetScaleを検索して追加するか、サーバーURLを手入力するカスタムコネクタにします。会話ごとに、チャット欄の「+」から「Connectors」を開いてオンにする必要があります。

カスタムコネクタのリモートMCP接続は、Free・Pro・Max・Team・Enterpriseの各プランで使えます。サポート記事によれば、Freeプランのカスタムコネクタは1件までです。

Claude Managed Agentsでは、platform.claude.comのCredential vaultで「Add credential」を開き、「MCP OAuth」を選びます。サーバーURLを入れ、アクセストークン欄とOAuthクライアント認証情報欄は空のまま「Connect」を押します。

つながらないときの確認順

1. クライアントを再起動する — 設定直後は再読み込みが要ることがあります。
2. サーバーURLを見る — ホスト型のhttps://mcp.pscale.dev/mcp/planetscaleか、Insights専用のURLかを取り違えていないか確かめます。
3. 再認証する — スコープやトークンを変えたあとは、新しいトークンを取り直します。
4. アクセス権を見直す — 期待するデータが見えないときは、PlanetScaleアカウント側の権限を確認します。
5. サービストークンの場合は権限表に戻る — 権限不足のツールだけが失敗します。

接続一覧への反映が遅く感じるときは、Claude Code側のキャッシュ挙動が原因のことがあります。MCP_DISCOVERY_CACHEの挙動で、表示が遅れる理由を確かめられます。

まとめ

人が操作する場面ではOAuthのスコープで見せる範囲を絞り、機械が動かす場面ではサービストークンのconnect_*権限を必要な分だけ付けるのが、PlanetScale MCPサーバーの安全な使い方です。トークンを使うなら.mcp.jsonには実値を書かず、環境変数の展開を通します。