Planetscale MCP Agent Operating Model

MCP agent operating model

Purpose

Define how agents should use PlanetScale MCP safely. Agents should use production telemetry to generate useful work while avoiding autonomous production changes.

Default MCP choice

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.

AGENTS.md guidance

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 planetscale-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.

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.

Agent loops

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.

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.

Traffic Control loop

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.

Scheduled loops (cron / Automations)

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 ../planetscale-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 1 — propose through the review workflow (no authorization needed)

• 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.