Skip to main content
PlanetScale instructions for setting up AI agents with PlanetScale Postgres and Vitess/MySQL. Use the Markdown export when pasting this prompt into an agent session. Agents with the PlanetScale CLI installed can also fetch setup instructions in JSON:
Commands on this page require pscale 0.292.0 or later. Install or upgrade the CLI in the prerequisites below before running the setup steps. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run setup commands unless a step requires browser approval they must perform.

​
Install PlanetScale Skills and MCP

Use the section for your agent below. Skills cover operational workflows (assessment, safety review, Insights, schema recommendations). The hosted MCP server gives MCP clients access to PlanetScale account data.

​
Prerequisites

Install the PlanetScale CLI if it is not already available (0.292.0 or later):
Verify the CLI version and agent automation support:
If agent-guide is unknown or auth check --format json prints nothing, upgrade with brew upgrade pscale. If auth check returns "status": "action_required", follow issues and next_steps in the JSON (typically pscale auth login --format json or service-token flags for CI). Always pass --format json on pscale commands in automation. Put --org on resource subcommands (database, branch, sql, …), not on root pscale.

​
Install skills (all agents)

Setup script (recommended):
The script installs to every agent it finds (~/.cursor/skills/, ~/.claude/skills/, ~/.agents/skills/). For other agents, pass the skills directory explicitly:
Skills CLI:
After installing, load skill 14-pscale-cli-automation for CLI conventions and 00-safe-orchestrator when the user asks for a full PlanetScale assessment. See github.com/planetscale/skills.

​
Cursor, GitHub Copilot, and VS Code

MCP — add to .cursor/mcp.json, .vscode/mcp.json, or your agent’s MCP config under "mcpServers":
Or use the CLI helper for Cursor:
OAuth triggers automatically on first PlanetScale MCP tool use. See PlanetScale MCP server for details. Skills — use script/setup above or install into <project>/.cursor/skills/ for project-scoped workflows.

​
Claude Code

Hosted MCP (recommended):
Or ask the CLI for the current command:
Install skills with npx skills add planetscale/skills -g -y or script/setup.

​
Zed

See the current MCP docs — the CLI prints setup instructions:
Install skills with script/setup or npx skills add planetscale/skills -g -y.

​
Headless / CI (no browser)

Use a PlanetScale service token instead of OAuth login. Pass credentials on each command:
Do not retry these under service-token auth. The failure is by design. See the service token automation matrix for full guidance.

​
Project context (application repositories)

In the user’s application repo, add or update a project AGENTS.md with:
  • PlanetScale organization, database, branch, and engine (Postgres or Vitess)
  • Whether agents may run write SQL or only read-only queries
  • Approval rules for schema changes, Traffic Control, webhooks, and credentials
Do not edit project AGENTS.md without user approval. See skill 09-mcp-agent-operating-model in planetscale/skills.

​
Verify setup

Confirm pscale 0.292.0+ and JSON auth work, then run:
When setup is complete, tell the user:

​
Resources

These instructions are published at https://planetscale.com/docs/agent-setup/prompt.md so you can re-verify their authenticity at any time.