> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent setup prompt

> Official PlanetScale instructions for AI agents to install skills, configure MCP, and authenticate the CLI.

<Note>
  **For agents:** fetch this page as Markdown at [Markdown export](/agent-setup/prompt.md) (production URL: `https://planetscale.com/docs/agent-setup/prompt.md`). You can also run `pscale agent-guide --format json` when the PlanetScale CLI is installed.
</Note>

<Note>
  **Requires `pscale` 0.292.0 or later** for `agent-guide`, JSON `auth check`/`login`, hosted `mcp install`, and `pscale sql`. Install or upgrade with `brew install pscale` or `brew upgrade pscale`. If `pscale agent-guide` is unknown, upgrade the CLI first.
</Note>

These are official instructions from PlanetScale to set up a good AI development environment for PlanetScale Postgres and Vitess/MySQL. Commands below require **`pscale` 0.292.0+**.

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**):

```bash theme={null}
brew install pscale
brew upgrade pscale
```

Verify the CLI version and agent automation support:

```bash theme={null}
pscale version
pscale agent-guide --format json
pscale auth check --format json
```

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):**

```bash theme={null}
git clone https://github.com/planetscale/skills.git
cd skills && script/setup
```

The script installs to every agent it finds (`~/.cursor/skills/`, `~/.claude/skills/`, `~/.agents/skills/`). For other agents, pass the skills directory explicitly:

```bash theme={null}
script/setup ~/.codex/skills
```

**Skills CLI:**

```bash theme={null}
npx skills add planetscale/skills -g -y
```

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](https://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"`:

```json theme={null}
"planetscale": {
  "url": "https://mcp.pscale.dev/mcp/planetscale"
}
```

Or use the CLI helper for Cursor:

```bash theme={null}
pscale mcp install --target cursor --format json
```

OAuth triggers automatically on first PlanetScale MCP tool use. See [PlanetScale MCP server](/connect/mcp) for details.

**Skills** — use `script/setup` above or install into `<project>/.cursor/skills/` for project-scoped workflows.

***

### Claude Code

Hosted MCP (recommended):

```bash theme={null}
claude mcp add --transport http "planetscale" https://mcp.pscale.dev/mcp/planetscale
```

Or ask the CLI for the current command:

```bash theme={null}
pscale mcp install --target claude-code --format json
```

Install skills with `npx skills add planetscale/skills -g -y` or `script/setup`.

***

### Zed

See the current MCP docs — the CLI prints setup instructions:

```bash theme={null}
pscale mcp install --target zed --format json
```

Install skills with `script/setup` or `npx skills add planetscale/skills -g -y`.

***

### Headless / CI (no browser)

Use a [PlanetScale service token](/cli/service-tokens) instead of OAuth login. Pass credentials on each command:

```bash theme={null}
pscale auth check --format json \
  --service-token-id "$PLANETSCALE_SERVICE_TOKEN_ID" \
  --service-token "$PLANETSCALE_SERVICE_TOKEN"
```

***

## 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](https://github.com/planetscale/skills).

***

## Verify setup

Confirm **`pscale` 0.292.0+** and JSON auth work, then run:

```bash theme={null}
pscale agent-guide --format json
pscale auth check --format json
pscale org list --format json
```

When setup is complete, tell the user:

```text theme={null}
PlanetScale Agent Setup Complete

✓ Skills   installed (planetscale/skills)
✓ MCP      https://mcp.pscale.dev/mcp/planetscale
✓ CLI      pscale auth check --format json

⚡ Restart your agent to load MCP servers
```

***

## Resources

| Resource                           | URL                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------- |
| This prompt (Markdown)             | `https://planetscale.com/docs/agent-setup/prompt.md`                      |
| CLI agent guide                    | `pscale agent-guide --format json` or [CLI agent-guide](/cli/agent-guide) |
| PlanetScale skills                 | [github.com/planetscale/skills](https://github.com/planetscale/skills)    |
| MCP setup                          | [PlanetScale MCP server](/connect/mcp)                                    |
| AI & automation overview           | [AI-enhanced development](/connect/ai-tooling)                            |
| `pscale sql` (non-interactive SQL) | [CLI sql](/cli/sql)                                                       |

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