planetscale-mcp-agent-operating-model

MCP エージェントの運用モデル

目的

エージェントが PlanetScale MCP を安全に使用する方法を定めます。エージェントは、本番環境に自律的な変更を加えることなく、本番環境のテレメトリを活用して有用な作業を行います。

MCP のデフォルト選択

タスクに Insights と Schema Recommendations だけが必要な場合は、PlanetScale MCP のインサイト専用サーバーを使用します。

Insights 以外のデータベース／スキーマへのアクセスがタスクで明示的に必要な場合にのみ、フル版の PlanetScale MCP サーバーを使用します。読み取り専用のスコープを優先してください。

フル版の MCP サーバーにはクエリ実行ツールがあります。オペレーターが特定の非本番環境での操作、または慎重にレビューされた本番環境での操作を明示的に承認しない限り、書き込みクエリツールは無効として扱ってください。

AGENTS.md のガイダンス

AGENTS.md という同じ名前の文書が 2 種類あり、それぞれ異なる役割を果たします。

1. CLI エージェントガイド — pscale に同梱されています（ planetscale/cli リポジトリ内の AGENTS.md、または pscale agent-guide --format json）。認証、--format json、フラグの配置、pscale sql について説明しています。この skills pack で同じ規約を適用するには、スキル planetscale-pscale-cli-automation を読み込んでください。

2. プロジェクトエージェントガイド — アプリケーションのリポジトリにある AGENTS.md（または同等のファイル）です。このアプリのデータベースの指定方法と承認ポリシーについて説明しています。

リポジトリ内で作業する場合は、プロジェクトのデータベース指定セクションを AGENTS.md または同等のプロジェクト指示に追加することを推奨してください。

• PlanetScale の組織。
• データベース。
• ブランチ。
• エンジン：Vitess または Postgres。
• 本番ブランチ名。
• エージェントが MCP のインサイト専用サーバーとフル版 MCP のどちらを使用できるか。
• 書き込みクエリが禁止されているかどうか。
• スキーマ、Traffic Control、ウェブフック、ロール、ネットワークの変更に必要な承認手順。

承認なしに AGENTS.md を編集しないでください。

自律的に実行してよい安全なタスク

デフォルトで許可されている操作：

• Insights を読む。
• スキーマの推奨事項を読む。
• スキーマのメタデータを読む。
• 既存のウェブフックと Traffic Control の設定を読む。
• ブランチのメタデータを読む。
• リポジトリのコードを調べる。
• クエリパターンとコードを照合する。
• 課題を登録する。
• プルリクエストを作成する。
• 開発ブランチを作成する。
• 非本番の開発ブランチに DDL とマイグレーションを適用する。
• レビューワークフローによって保護されたブランチへのデプロイリクエストを作成する。
• Traffic Control の予算案を作成する。
• ウェブフックの受信要件案を作成する。

PR とデプロイリクエストを組み合わせたワークフローがある場合、スキーマの推奨事項に対するデフォルトの成果物は、レビュー可能な一式です。つまり、DDL を適用した開発ブランチ、根拠（フィンガープリント、メトリクス、期待される効果）を含む PR、そしてオープン状態のデプロイリクエストです。人間が行うのはマージ／デプロイの判断であり、提案の作成を後押しすることではありません。

デフォルトで許可されていない操作（レビューゲートが必要な操作およびレビューできない変更）：

• 本番環境に対して書き込み SQL を実行する。
• 本番ブランチに対して DDL を直接実行する。
• デプロイリクエストをデプロイする／本番環境にスキーマを適用する。
• プルリクエストをマージする。
• ウェブフックを作成する。
• Traffic Control の予算を作成または適用する。
• 認証情報をローテーションする。
• ロールを変更する。
• IP 制限またはプライベート接続を変更する。
• ブランチを復元または昇格する。

エージェントのループ

日次の推奨ループ

1. オープン状態のスキーマの推奨事項を読む。
2. Insights の上位の回帰を読む。
3. リポジトリのコードと照合する。
4. 優先順位を付けた課題または PR を作成する。
5. 人間がレビューする。
6. データベースに影響する操作は、人間が承認する。

異常対応ループ

1. 異常を受信するか、確認する。
2. 影響を受けるクエリパターンとタグを収集する。
3. 発生元のルート／ジョブ／デプロイを特定する。
4. インシデントの記録と修正案を作成する。
5. コードの修正が明白な場合は、PR を作成する。
6. データベースの変更が必要な場合は、変更案のみを作成する。

Traffic Control のループ

1. Insights／タグから安全でないトラフィックの範囲を特定する。
2. warn モードの予算案を作成する。
3. 人間が作成を承認する。
4. 警告を確認する。
5. 検証後にのみ、人間が enforce モードを承認する。

スケジュールされたループ（cron / Automations）

上記のループは対話形式で実行されます。人間が介在しないスケジュール実行も、2 つのティアで可能です。ティア 2 では ../planetscale-autonomous-execution-mode/SKILL.md に従った継続的な認可が必要ですが、ティア 1 では必要ありません。

どちらのティアでも、スケジュールされたすべてのループで、実行開始時に認可を再確認し、設定済みの配信チャネルにステータスをストリーミングし、実行ログを保存し、重複登録を避けます（同じフィンガープリント／推奨 ID の課題がすでにオープンの場合は再登録しません）。

ティア 1 — レビューワークフローを通じて提案する（認可不要）

• 推奨事項から PR へのループ（毎日）：MCP を通じてオープンなスキーマの推奨事項を一覧表示します。ワークフローに一致する新しい推奨事項（加算的または破壊的 — PR レビューがゲートです）ごとに、開発ブランチを作成し、DDL を適用して、フィンガープリント、メトリクス、期待される効果を含む PR をオープンし、デプロイリクエストをオープンします。人間がマージ／デプロイの 1 回の操作でリリースできる状態になった時点で、レビュー可能な単位が完了します。出力：推奨事項ごとのブランチ、PR、デプロイリクエスト。
• リグレッション監視（毎時またはデプロイごと）：上位パターンを保存済みのベースライン（p50/p99、読み取り行数、実行回数）と比較します。重大なリグレッションが発生した場合、クエリタグからデプロイ SHA を特定し、パターンとコミット範囲を関連付けたレポートを登録します。出力：レポート。
• タグ付与率の監査（毎週）：タグが付与されたクエリ時間の割合を測定し、コストの高い未タグ付けパターンと、可能性の高いコードパスを一覧表示して、追跡用の課題を 1 件オープンまたは更新します。出力：課題。
• 異常のトリアージ（Webhook によるトリガー、ポーリングなし）：branch.anomaly の発生時に、影響を受けるパターンを収集し、原因を推定して分類し、インシデントチャネルにトリアージメモを投稿します。出力：トリアージメモ。
• 設定ドリフトの確認（毎日）：現在の safe-migrations フラグ、Webhook 設定、ロール一覧、バックアップスケジュールを前回の評価レポートと比較し、差異を報告します。出力：レポート。

ティア 2 — レビューゲートのアクションを実行する（継続的な認可が必要）

• 推奨事項デプロイ担当（毎日、PR ループの後）：許可リストに一致するオープンなデプロイリクエストをデプロイします。一般的には、「加算的 DDL、PR 承認済みまたはオープンな推奨事項から作成、ロールバック可能期間付きでデプロイ、1 回の実行につき最大 N 件」といった条件です。その後、スキーマの読み戻しと、対象フィンガープリントに対する Insights の追跡確認を行います。認可に実行時に検証可能な条件が明記されている場合に限り（例：「Insights で実行時に確認し、過去 30 日間読み取りがゼロのインデックスのみを削除する」）、破壊的 DDL を自律的にデプロイします。組織がデプロイ前に PR 承認を求める場合、承認済み PR によりレビュ－ゲートが満たされ、認可の対象は機械的なデプロイのみです。
• ブランチの整理（毎週）：オープンなデプロイリクエストがなく、認可された期間を超えている開発ブランチを削除します。本番ブランチや保護されたブランチには決して触れません。
• 警告予算の管理（毎週）：許可リストに一致する、新たに特定されたコストの高いスライスに対して、警告モードの Traffic Control 予算を作成し、既存の予算における警告件数を報告します。認可で特定の予算が指定されていない限り、自律的に強制モードに移行することはありません。
• 認証情報の有効期限の適用（毎日）：認可された最大有効期間を過ぎたパスワードを削除またはフラグ付けします。ただし、認可に対象のロールが列挙され、ローテーション手順書が存在する場合に限ります。

ループのアンチパターン

• Webhook ですでに配信されるイベントを cron で MCP にポーリングすること — トリガーには Webhook を使用し、ベースライン、スイープ、監査には cron を使用します。
• 許可リストが範囲の限定された操作ではなく、「正常な状態を維持する」といった意図になっているティア 2 ループ。
• ステータスを配信するチャネルなしに変更を加えるループ。
• 無制限のファンアウト：1 回の実行で、実行ごとの上限なしにすべてのオープンな推奨事項を適用すること。

クエリ実行の安全対策

読み取りクエリの場合：

• 利用可能な場合はレプリカを優先してください。
• planetscale_execute_read_query は、ブランチにレプリカが設定されている場合、デフォルトで読み取りをレプリカにルーティングします（use_replica: true）。書き込み直後の状態の確認やプライマリのみの動作など、プライマリから読み取る必要があるタスクの場合に限り、use_replica: false を設定してください。
• エージェントによる作業には、ソースタグ／コメントを追加してください。
• 上限のないスキャンは避けてください。
• 明示的な承認がない限り、本番環境での EXPLAIN ANALYZE は避けてください。
• 結果の件数を制限してください。
• 必要かつ承認済みの場合を除き、機密列へのクエリは避けてください。
• 行レベルセキュリティが設定された Postgres テーブルでは、MCP の読み取りロールが pg_read_all_data を使用し、RLS を回避しないことに留意してください。読み取りクエリの結果が 0 行または件数 0 で、MCP の応答に RLS が結果をフィルタリングしている可能性があるという警告が表示された場合、承認済みの方法で確認するまでは、その結果をポリシーによってフィルタリングされた／不明なものとして扱ってください。テーブルが空だと結論付けてはいけません。
• Postgres の CPU 使用率が高い問題をデバッグする場合は、CPU 使用率順に並べた Insights データを使用してください（利用可能な場合は MCP 経由、または Insights API で sort=cpuTime を指定）。CPU 時間のメトリクスは Postgres 専用です。Vitess では同じ CPU 順のビューを求めないでください。

書き込みクエリの場合：

• デフォルトでは禁止です。
• 承認された場合は、本番環境以外のブランチを優先してください。
• SQL の内容を正確にレビューしてください。
• ロールバック計画を必須とします。
• ブランチ名とデータベース名の確認を必須とします。

出力

以下を返してください：

• 推奨する MCP サーバーの選択。
• 必要なスコープ。
• 追加する AGENTS.md の指示。
• 自律的に実行できる作業。
• 禁止される作業。
• 提案するエージェントのループ。
• 承認ゲート。

最後に、次の文を記載してください：

「MCP の書き込みツールやデータベースの変更は一切使用していません。」