Back to Details

planetscale-mcp-agent-operating-model

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP agent operating model

MCP Agent 操作模型

Purpose

目的

Define how agents should use PlanetScale MCP safely. Agents should use production telemetry to generate useful work while avoiding autonomous production changes.
定义Agent应如何安全使用PlanetScale MCP。Agent应利用生产环境遥测数据生成有用的工作成果，同时避免自主执行生产环境变更。

Default MCP choice

默认MCP选择

Use the PlanetScale MCP insights-only server when the task only needs Insights and Schema Recommendations.
Use the full PlanetScale MCP server only when the task explicitly requires database/schema access beyond Insights. Prefer read-only scopes.
The full MCP server has query execution tools. Treat write query tools as disabled unless the operator explicitly approves a specific non-production action or a carefully reviewed production action.
当任务仅需Insights和Schema Recommendations时，使用仅支持Insights的PlanetScale MCP服务器。
只有当任务明确需要超出Insights范围的数据库/Schema访问权限时，才使用完整的PlanetScale MCP服务器。优先选择只读权限范围。
完整MCP服务器具备查询执行工具。除非操作者明确批准特定的非生产环境操作或经过严格审核的生产环境操作，否则默认禁用写入查询工具。

AGENTS.md guidance

AGENTS.md 指南

Two different documents both named 
AGENTS.md
serve different purposes:
  1. CLI agent guide — shipped with 
    pscale
    (
    AGENTS.md
    in the planetscale/cli repo, or 
    pscale agent-guide --format json
    ). Covers auth, 
    --format json
    , flag placement, and 
    pscale sql
    . Load skill 
    14-pscale-cli-automation
    for the same conventions inside this skills pack.
  2. Project agent guide — your application repository's 
    AGENTS.md
    (or equivalent). Covers database targeting and approval policy for this app.
When working inside a repository, recommend adding a project database targeting section to 
AGENTS.md
or equivalent project instructions:
  • PlanetScale organization.
  • Database.
  • Branch.
  • Engine: Vitess or Postgres.
  • Production branch name.
  • Whether agents may use MCP insights-only or full MCP.
  • Whether write queries are forbidden.
  • Required approval protocol for schema, Traffic Control, webhooks, roles, and network changes.
Do not edit 
AGENTS.md
without approval.
有两份同名文档
AGENTS.md
，用途各不相同：
  1. CLI Agent 指南 — 随
    pscale
    发布（位于planetscale/cli仓库的
    AGENTS.md
    ，或通过
    pscale agent-guide --format json
    获取）。涵盖认证、
    --format json
    、参数位置及
    pscale sql
    相关内容。在本技能包中加载
    14-pscale-cli-automation
    技能可遵循相同规范。
  2. 项目Agent指南 — 应用代码仓库中的
    AGENTS.md
    （或等效文档）。涵盖当前应用的数据库目标定位及审批策略。
在代码仓库内工作时，建议在
AGENTS.md
或等效项目说明文档中添加项目级数据库目标定位章节：
  • PlanetScale组织名称
  • 数据库名称
  • 分支名称
  • 引擎：Vitess 或 Postgres
  • 生产分支名称
  • Agent是否可使用仅支持Insights的MCP或完整MCP
  • 是否禁止写入查询
  • Schema、Traffic Control、Webhook、角色及网络变更所需的审批流程
未经批准不得编辑
AGENTS.md
。

Safe autonomous tasks

安全自主任务

Allowed by default:
  • Read Insights.
  • Read schema recommendations.
  • Read schema metadata.
  • Read existing webhooks and Traffic Control configuration.
  • Read branch metadata.
  • Inspect repository code.
  • Correlate query patterns with code.
  • File issues.
  • Open pull requests.
  • Create development branches.
  • Apply DDL and migrations to non-production development branches.
  • Open deploy requests into branches protected by a review workflow.
  • Draft Traffic Control budget proposals.
  • Draft webhook receiver requirements.
Where a PR + deploy-request workflow exists, the default deliverable for a schema recommendation is the complete reviewable unit: development branch with the DDL applied, PR with evidence (fingerprint, metrics, expected effect), and an open deploy request. The human action is the merge/deploy decision, not shepherding the proposal into existence.
Not allowed by default (the review-gate actions and non-reviewable mutations):
  • Execute write SQL against production.
  • Execute DDL directly against production branches.
  • Deploy a deploy request / apply schema to production.
  • Merge pull requests.
  • Create webhooks.
  • Create or enforce Traffic Control budgets.
  • Rotate credentials.
  • Change roles.
  • Change IP restrictions or private connectivity.
  • Restore or promote branches.
默认允许的操作：
  • 读取Insights数据
  • 读取Schema Recommendations
  • 读取Schema元数据
  • 读取现有Webhook和Traffic Control配置
  • 读取分支元数据
  • 检查代码仓库代码
  • 将查询模式与代码关联
  • 创建Issue
  • 发起Pull Request
  • 创建开发分支
  • 在非生产开发分支上应用DDL和迁移
  • 向受审核工作流保护的分支发起部署请求
  • 草拟Traffic Control预算提案
  • 草拟Webhook接收器需求
当存在PR+部署请求工作流时，Schema Recommendations的默认交付成果是完整的可审核单元：已应用DDL的开发分支、附带证据（指纹、指标、预期效果）的PR，以及已发起的部署请求。人工操作仅需负责合并/部署决策，无需跟进提案的创建过程。
默认禁止的操作（需审核的操作及不可审核的变更）：
  • 对生产环境执行写入SQL
  • 直接对生产分支执行DDL
  • 部署请求/将Schema应用到生产环境
  • 合并Pull Request
  • 创建Webhook
  • 创建或强制执行Traffic Control预算
  • 轮换凭证
  • 修改角色
  • 修改IP限制或私有连接设置
  • 恢复或升级分支

Agent loops

Agent 循环流程

Daily recommendation loop

每日建议循环

  1. Read open schema recommendations.
  2. Read top Insights regressions.
  3. Correlate with repository code.
  4. Generate ranked issues or PRs.
  5. Human reviews.
  6. Human approves any database-affecting action.
  1. 读取待处理的Schema Recommendations
  2. 读取Insights中排名靠前的性能退化项
  3. 与代码仓库代码关联
  4. 生成优先级排序的Issue或PR
  5. 人工审核
  6. 人工批准任何影响数据库的操作

Anomaly loop

异常处理循环

  1. Receive or inspect anomaly.
  2. Gather affected query patterns and tags.
  3. Identify source route/job/deploy.
  4. Produce incident note and proposed remediation.
  5. If code fix is obvious, open PR.
  6. If database change is needed, create a proposed change set only.
  1. 接收或检查异常
  2. 收集受影响的查询模式及标签
  3. 定位来源路由/任务/部署版本
  4. 生成事件记录及建议修复方案
  5. 若代码修复方案明确，发起PR
  6. 若需数据库变更，仅生成建议变更集

Traffic Control loop

Traffic Control 循环

  1. Identify unsafe traffic slice from Insights/tags.
  2. Draft 
    warn
    budget proposal.
  3. Human approves creation.
  4. Observe warnings.
  5. Human approves enforce mode only after validation.
  1. 从Insights/标签中识别不安全的流量分片
  2. 草拟
    warn
    模式的预算提案
  3. 人工批准创建
  4. 观察警告情况
  5. 仅在验证通过后，人工批准切换至强制模式

Scheduled loops (cron / Automations)

定时循环（Cron / 自动化）

The loops above run interactively. They can also run on a schedule with no human in the loop, in two tiers. Tier 2 requires a standing authorization per 
../13-autonomous-execution-mode/SKILL.md
; Tier 1 requires none.
Every scheduled loop, both tiers: re-read authorization at run start, stream status to a configured delivery channel, persist a run log, and avoid filing duplicates (do not re-file an issue that is already open for the same fingerprint/recommendation ID).
上述循环为交互式运行。它们也可在无人干预的情况下按计划运行，分为两个层级。Tier 2需要根据
../13-autonomous-execution-mode/SKILL.md
获取长期授权；Tier 1无需授权。
所有定时循环（两个层级）均需：在运行开始时重新读取授权信息、将状态流式传输至指定交付渠道、保存运行日志、避免重复提交（不得为同一指纹/建议ID重复提交已存在的Issue）。

Tier 1 — propose through the review workflow (no authorization needed)

Tier 1 — 通过审核工作流提交提案（无需授权）

  • Recommendation-to-PR loop (daily): list open schema recommendations via MCP; for each new one matching the workflow (additive or destructive — the PR review is the gate), create a development branch, apply the DDL, open a PR with fingerprint, metrics, and expected effect, and open the deploy request. The reviewable unit is complete when a human can ship it with one merge/deploy action. Output: branch + PR + deploy request per recommendation.
  • Regression watch (hourly or per-deploy): compare top patterns against a stored baseline (p50/p99, rows read, execution count); on material regression, identify the deploy SHA from query tags and file a report linking pattern to commit range. Output: report.
  • Tag coverage audit (weekly): measure percentage of query time carrying tags; list untagged high-cost patterns with likely code paths; open or update a single tracking issue. Output: issue.
  • Anomaly triage (webhook-triggered, not polled): on 
    branch.anomaly
    , gather affected patterns, classify probable cause, post triage note to the incident channel. Output: triage note.
  • Posture drift check (daily): diff current safe-migrations flags, webhook config, role list, and backup schedule against the last assessment report; report any drift. Output: report.
  • 建议转PR循环（每日）：通过MCP列出待处理的Schema Recommendations；对于符合工作流的每条新建议（新增或删除类——PR审核为管控节点），创建开发分支、应用DDL、发起附带指纹、指标及预期效果的PR，并发起部署请求。当人工可通过一次合并/部署操作完成交付时，可审核单元即准备完毕。输出：每条建议对应一个分支+PR+部署请求。
  • 性能退化监控（每小时或每次部署后）：将排名靠前的查询模式与存储的基准数据（p50/p99、读取行数、执行次数）对比；若出现实质性性能退化，从查询标签中定位部署SHA并提交关联查询模式与提交范围的报告。输出：报告。
  • 标签覆盖率审计（每周）：统计携带标签的查询时间占比；列出未标记的高成本查询模式及可能的代码路径；创建或更新单个跟踪Issue。输出：Issue。
  • 异常分类（由Webhook触发，非轮询）：收到
    branch.anomaly
    事件时，收集受影响的查询模式、分类可能原因、将分类记录发布至事件渠道。输出：分类记录。
  • 配置漂移检查（每日）：对比当前安全迁移标志、Webhook配置、角色列表及备份计划与上次评估报告的差异；报告任何漂移情况。输出：报告。

Tier 2 — execute the review-gate action (standing authorization required)

Tier 2 — 执行需审核的操作（需长期授权）

  • Recommendation deployer (daily, after the PR loop): deploy open deploy requests that match the allowlist — typically "additive DDL, PR approved or authored from an open recommendation, deploy with revert window, max N per run" — then verify via schema read-back and an Insights follow-up on the target fingerprint. Destructive DDL deploys autonomously only when the authorization states a runtime-verifiable bound (e.g. "drop only indexes with zero reads in 30 days, confirmed via Insights at run time"). Where the org requires PR approval before deploy, an approved PR satisfies the review gate and the authorization covers only the mechanical deploy.
  • Branch hygiene (weekly): delete development branches older than the authorized age bound with no open deploy request; never touch production or protected branches.
  • Warn-budget gardener (weekly): create warn-mode Traffic Control budgets for newly identified expensive slices matching the allowlist; report warn counts on existing budgets. Enforce mode is never entered autonomously unless the authorization names the specific budget.
  • Credential expiry enforcement (daily): delete or flag passwords past the authorized max age, only where the authorization lists the affected roles and a rotation runbook exists.
  • 建议部署器（每日，PR循环之后）：部署符合允许列表的待处理部署请求——通常为“新增类DDL、PR已批准或源自待处理建议、部署时设置回滚窗口、每次运行最多N个”——随后通过Schema回读及针对目标指纹的Insights跟进验证。仅当授权中包含可运行时验证的约束条件（例如“仅删除30天内无读取操作的索引，运行时通过Insights确认”）时，才可自主执行破坏性DDL部署。若组织要求部署前需PR批准，则已批准的PR可满足审核要求，授权仅涵盖机械部署操作。
  • 分支清理（每周）：删除超过授权保留期限且无待处理部署请求的开发分支；绝不触碰生产分支或受保护分支。
  • 警告预算管理（每周）：为符合允许列表的新识别高成本流量分片创建
    warn
    模式的Traffic Control预算；报告现有预算的警告次数。除非授权中明确指定具体预算，否则绝不自主切换至强制模式。
  • 凭证过期强制执行（每日）：删除或标记超过授权最大有效期的密码，仅适用于授权中列出的受影响角色且存在轮换手册的情况。

Loop anti-patterns

循环反模式

  • Polling MCP on a cron for events webhooks already deliver — use the webhook as the trigger; use cron for baselines, sweeps, and audits.
  • A Tier 2 loop whose allowlist is an intent ("keep things healthy") rather than bounded operations.
  • Loops that mutate without a delivery channel for status.
  • Unbounded fan-out: one run applying every open recommendation at once with no per-run cap.
  • 已有Webhook推送事件仍通过Cron轮询MCP——应使用Webhook作为触发机制；Cron仅用于基准检查、全面扫描及审计。
  • Tier 2循环的允许列表为模糊意图（如“保持系统健康”）而非明确的受限操作。
  • 执行变更但未通过交付渠道同步状态的循环。
  • 无限制扩散：单次运行应用所有待处理建议且无单次运行数量上限。

Query execution safeguards

查询执行安全防护

—

读取查询

For read queries:
  • Prefer replicas when available.
  • planetscale_execute_read_query
    routes reads to replicas by default when a branch has replicas configured (
    use_replica: true
    ). Set 
    use_replica: false
    only when the task needs primary-read semantics, such as checking immediately-after-write state or primary-only behavior.
  • Add source tags/comments for agent work.
  • Avoid unbounded scans.
  • Avoid 
    EXPLAIN ANALYZE
    on production unless explicitly approved.
  • Limit result sizes.
  • Avoid querying sensitive columns unless required and approved.
  • For Postgres tables with row-level security, remember that the MCP read role uses 
    pg_read_all_data
    and does not bypass RLS. If a read query returns zero rows or a zero count and the MCP response warns that RLS may be filtering results, treat the result as policy-filtered/unknown until confirmed through an approved path; do not conclude the table is empty.
  • When debugging high CPU on Postgres, use Insights data sorted by CPU usage (via MCP where available, or 
    sort=cpuTime
    on the Insights API). CPU time metrics are Postgres-only; do not ask for the same CPU-sorted view on Vitess.
For write queries:
  • Default is forbidden.
  • If approved, prefer non-production branch.
  • Require exact SQL review.
  • Require rollback plan.
  • Require branch and database name confirmation.
  • 优先使用副本（若可用）。
  • 当分支配置有副本时，
    planetscale_execute_read_query
    默认将读取请求路由至副本（
    use_replica: true
    ）。仅当任务需要主节点读取语义时（例如检查写入后的即时状态或主节点专属行为），才设置
    use_replica: false
    。
  • 为Agent工作添加来源标签/注释。
  • 避免无边界扫描。
  • 除非明确批准，否则禁止在生产环境使用
    EXPLAIN ANALYZE
    。
  • 限制结果集大小。
  • 除非必要且已获批，否则禁止查询敏感列。
  • 对于启用行级安全（RLS）的Postgres表，需注意MCP读取角色使用
    pg_read_all_data
    且无法绕过RLS。若读取查询返回零行或零计数且MCP响应警告RLS可能过滤结果，需将结果视为受策略过滤/未知状态，直至通过获批路径确认；不得直接判定表为空。
  • 调试Postgres高CPU问题时，使用按CPU使用率排序的Insights数据（若可通过MCP获取，或在Insights API上使用
    sort=cpuTime
    ）。CPU时间指标为Postgres专属；请勿要求在Vitess上使用相同的CPU排序视图。

Output

写入查询

Return:
  • Recommended MCP server choice.
  • Required scopes.
  • AGENTS.md instructions to add.
  • Allowed autonomous work.
  • Disallowed work.
  • Proposed agent loops.
  • Approval gates.
End with:
“No MCP write tools or database mutations have been used.”
  • 默认禁止。
  • 若获批，优先使用非生产分支。
  • 要求对SQL语句进行精确审核。
  • 要求制定回滚计划。
  • 要求确认分支及数据库名称。
—

输出内容

—
返回：
  • 推荐的MCP服务器选择
  • 所需权限范围
  • 需添加至AGENTS.md的说明
  • 允许的自主工作内容
  • 禁止的工作内容
  • 建议的Agent循环流程
  • 审批节点
结尾需包含： “No MCP write tools or database mutations have been used.”