PlanetScale MCP Server Cursor IDE Setup 2026: OAuth, Branches & Query Safeguards

How do you set up the PlanetScale MCP server in Cursor IDE? Add one url entry pointing at https://mcp.pscale.dev/mcp/planetscale to ~/.cursor/mcp.json, restart Cursor, and authorize via OAuth in the browser on first tool call. No npm package, no key to generate for the common case — PlanetScale hosts the server itself, the same pattern Stripe and a handful of other 2026-era MCP servers have moved to.

Once connected, Cursor can list your organizations, branches, and schemas, run read and write queries against a real branch, and pull Insights and schema recommendations — all from chat, without a tab open to the PlanetScale dashboard.

What the PlanetScale MCP Server Exposes

Sixteen tools, roughly split across four areas:

That range is deliberate — this isn't a narrow "run one query" tool, it's meant to replace switching to the PlanetScale dashboard for most day-to-day database work.

Prerequisites

Step 1: Add the Server to mcp.json

Open Cursor Settings → Tools & Integrations → New MCP Server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "planetscale": {
      "url": "https://mcp.pscale.dev/mcp/planetscale"
    }
  }
}

That's the entire config for the interactive, browser-authorized route.

Step 2: Authorize via OAuth

Restart Cursor. On the first tool call that touches PlanetScale, a browser window opens asking you to authorize the connection against your PlanetScale account. Approve it, and the session persists — there's no token sitting in mcp.json to leak from a shared config file.

Step 3: Verify

In Cursor chat:

List my PlanetScale organizations and the databases in each one

If you get back real org and database names, the connection is live.

Read-Only, Insights-Only Variant

If you want Cursor to see schema and performance data but never execute a write query at all, point at a different endpoint instead:

{
  "mcpServers": {
    "planetscale-insights": {
      "url": "https://mcp.pscale.dev/mcp/planetscale-insights-only"
    }
  }
}

This excludes write query execution entirely at the server level — a stronger guarantee than just "asking the AI nicely not to write," useful for a shared team config where you don't want every developer's session capable of mutating data.

Headless / CI Authentication

Browser OAuth doesn't work in a non-interactive environment. For that case, generate a PlanetScale service token and set it as an environment variable instead of relying on the OAuth flow:

{
  "mcpServers": {
    "planetscale": {
      "url": "https://mcp.pscale.dev/mcp/planetscale",
      "env": {
        "PLANETSCALE_API_TOKEN": "your-service-token-here"
      }
    }
  }
}

This bypasses the browser redirect entirely, which is the point — but it also means the token, not a revocable browser session, is now the thing controlling access. Scope the service token's permissions as tightly as your workflow allows.

Built-In Query Safeguards

The server blocks certain destructive patterns outright rather than just warning about them: UPDATE or DELETE statements without a WHERE clause, and TRUNCATE statements, are rejected before they run. Schema-changing DDL statements require explicit human confirmation in Cursor before executing.

Read queries default to routing through a replica when one is available, not the primary — set use_replica to false on the read-query tool if you specifically need primary-consistent reads (checking a write you just made, for instance).

Practical Workflows

Checking a schema before writing a migration

Show me the current schema for the orders table on the main branch, 
then help me write a migration that adds a shipped_at timestamp column.

Investigating slow queries

Pull the Insights data for the production database and show me the 
slowest queries from the last 24 hours.

Branch-aware debugging

Compare the schema on my dev-feature-x branch against main — 
did the migration I ran actually apply the index I expected?

Gotchas

This is a real database connection, not a sandbox. Write queries run against the branch you point them at. A dev branch insulates you from production, but "just try it" prompts against a branch with real data still do real writes — the blocked patterns (unscoped UPDATE/DELETE, TRUNCATE) are a safety net, not a substitute for pointing sessions at the right branch.

Replica routing means reads can lag primary writes. If you write a row and immediately ask Cursor to read it back and the read comes up empty, that's very likely replica lag, not a broken write — retry with use_replica: false before assuming something failed.

The insights-only endpoint is a separate URL, not a config flag. Switching a team from full access to read-only isn't a toggle in the same server entry — it's pointing at planetscale-insights-only instead of planetscale in the url field.

Troubleshooting

OAuth popup never fires
Confirm your Cursor version supports url-based remote servers (v0.47+). If it does, disconnect and reconnect the server from Cursor's MCP settings to force a fresh authorization attempt.

"Permission denied" on an org or database you can see in the dashboard
OAuth scopes to what your PlanetScale account can access, but org-level roles can further restrict what an individual member can do via API versus the UI. Check your role in that specific organization.

A write query got rejected that looks like it has a WHERE clause
Check for a typo that makes the clause technically absent from the parsed statement (a missing table alias reference, for example) — the safeguard checks the query as PlanetScale's API parses it, not just visually.

Service token setup ignores browser OAuth entirely — is that expected?
Yes. Once PLANETSCALE_API_TOKEN is set in the env block, the server authenticates with that token and skips the interactive OAuth flow, which is exactly what headless/CI use cases need it to do.

Frequently Asked Questions

Q: Do I need to install an npm package for the PlanetScale MCP server?
A: No. It's a remote, PlanetScale-hosted server — the entire config is a url field pointing at https://mcp.pscale.dev/mcp/planetscale. There's no local process to install or update.

Q: Can the PlanetScale MCP server run destructive queries by accident?
A: Some categories are blocked outright: unscoped UPDATE/DELETE (no WHERE clause) and TRUNCATE are rejected before execution, and DDL changes require explicit confirmation. Scoped writes with a WHERE clause do run for real, though — always confirm which branch a session is pointed at before asking for bulk changes.

Q: How do I stop the AI from writing to my database at all?
A: Point the server entry at the planetscale-insights-only endpoint instead of the default planetscale one. That variant excludes write query execution at the server level, not just as an AI instruction.

Q: Does OAuth work for automated or CI environments?
A: No — OAuth requires an interactive browser session. For headless use, set PLANETSCALE_API_TOKEN as an environment variable in the server's env block with a PlanetScale service token instead.

Q: Why did a query I just wrote for come back empty when I immediately read it?
A: Read queries default to a replica when one is available, and replicas can briefly lag behind primary writes. Set use_replica to false on the read tool, or wait a moment and retry, before assuming the write failed.

Related Guides