PlanetScale MCP Server: Setup and Production Permissions

The official PlanetScale MCP Server connects agents to database metadata, schema, Query Insights and optional SQL execution. Start with performance evidence and narrow permissions; add row access only when the investigation needs it. The official docs were checked on October 6, 2026.

This is a hosted HTTP integration. You do not need to invent a database proxy or install an unofficial package to get started. PlanetScale’s documentation also says the local-only pscale mcp server has been removed. Use the hosted instructions below rather than an older CLI tutorial. Official MCP guide.

Choose the endpoint and access before connecting

PlanetScale documents two endpoints:

https://mcp.pscale.dev/mcp/planetscale
https://mcp.pscale.dev/mcp/planetscale-insights-only

The second excludes planetscale_execute_read_query and planetscale_execute_write_query. It is the useful starting point for Insights and schema recommendations without query execution. OAuth lets you select no access, read-only access or full database access at organization or per-database level. Payment-method access is a separate permission choice. Endpoints and scopes.

My suggested production setup is one database, no payment-method access, and Insights/schema inspection first. Use a separate development authorization for write experiments. Endpoint selection controls exposed query tools; the grant controls what API operations are authorized. Verify both rather than relying on a prompt that says “read only.”

Install in Claude Code

PlanetScale’s direct installation command is:

claude mcp add --transport http "planetscale" https://mcp.pscale.dev/mcp/planetscale

Start Claude Code, run /mcp, select the PlanetScale server that needs authentication, and complete the browser flow. During authorization, choose the intended database and access level. The official guide also offers a PlanetScale Claude Code plugin, but adding the hosted endpoint directly is sufficient. Claude Code setup.

For evidence-only work, substitute the documented insights-only URL in the HTTP registration. After connecting, inspect the available tools and confirm the SQL execution tools are absent. Ask for the target branch schema before requesting a performance analysis so the conversation has a concrete database boundary.

Do not use a successful OAuth login as the only verification. Ask which organization, database and branch the agent is analyzing, then compare those names with the dashboard. A correct analysis of the wrong branch is still an unusable incident report.

Install in Cursor

Open the command palette, choose Cursor Settings, then Tools & MCP → New MCP Server. The official manual configuration is:

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

Save the configuration in .cursor/mcp.json, accept the login prompt and grant the intended access. The docs note that restarting Cursor may be necessary. As with Claude Code, the insights-only URL is available when SQL execution is unnecessary. Cursor setup.

For a repository shared by several developers, commit only the server definition if appropriate for your team. Keep credentials out of repository files. Verify each developer’s authorization independently; a shared endpoint definition does not establish a shared permission boundary.

Codex, VS Code and other clients

The official OAuth setup for Codex is:

codex mcp add planetscale --url https://mcp.pscale.dev/mcp/planetscale

Complete the browser prompt, then use /mcp inside Codex to confirm that the server is enabled and authenticated. Codex instructions.

For VS Code, the PlanetScale guide uses MCP: Add Server, selects HTTP and supplies the hosted URL. It also documents OpenCode, Gemini CLI, Amp, Claude connectors, Claude Managed Agents and Notion. Other clients need support for HTTP-hosted MCP servers; follow their current remote-server and authentication instructions rather than adapting a local stdio example. Supported clients.

The transport connection is only the first check. For each client, confirm the tool inventory, authorization and target names before using production evidence. If the client connects but a tool returns permission denied, inspect the grant for that operation rather than broadening access to the whole organization.

What the tools can actually do

The current official tool list groups naturally into these jobs. It is broader than a SQL console. Available tools.

Do not infer identical engine support from a similar tool name. The official list explicitly labels the Postgres log tool. Check the engine and the tool response for every workflow, and preserve unsupported or inaccessible observations as missing evidence.

Service tokens: metadata access is not SQL access

For a headless client, the hosted MCP server accepts the service-token secret as a Bearer token. It does not accept the token ID or id:secret. Set the secret in PLANETSCALE_API_TOKEN and use a client that supports custom headers. Service-token authentication.

The documented metadata/Insights read set is read_organization and read_databases at organization level, plus read_database and read_branch for each database. If only one database should be visible, the guide says to skip organization-wide read_databases and grant the per-database permissions. Those metadata permissions do not execute SQL. Read-only permission set.

For production read queries, add connect_production_read_only_branch and delete_production_read_only_branch_password; the latter lets the MCP delete its ephemeral reader credential. The guide also accepts delete_production_branch_password for deleting production reader credentials. Do not grant connect_production_branch for a read investigation, since it can create write credentials. Development read queries use a different connect/delete pair. Read-query permissions.

Codex can read the token from an environment variable without putting the expanded secret in its configuration:

codex mcp add planetscale \
  --url https://mcp.pscale.dev/mcp/planetscale-insights-only \
  --bearer-token-env-var PLANETSCALE_API_TOKEN

The official Claude Code header example expands the variable in the shell and writes the token into the MCP configuration. Keep that file private if you use that path. Claude.ai, Claude desktop, Claude Managed Agents and Notion use OAuth only, according to the service-token guide. Client configurations.

Read semantics and write safeguards

Queries execute over HTTP through the hosted server using short-lived credentials created on demand and deleted after execution. Read queries default to a replica when the branch has replicas configured; use_replica: false requests the primary. SQL includes a source=planetscale-mcp comment for identification in Insights. Query handling.

Postgres reads use a short-lived role with pg_read_all_data that does not bypass RLS. A zero-row response can include a postgres_rls_active warning listing affected relations. Preserve that warning in the analysis. Postgres query tools also accept postgres_database_name when the cluster contains databases beyond the default postgres database. Postgres query behavior.

Write safeguards block UPDATE or DELETE without WHERE, block TRUNCATE, and prompt the LLM to request human confirmation for DDL. That last behavior is a confirmation request, not a guarantee that every dangerous operation is impossible. A WHERE clause can still select more rows than intended. Write-query safeguards.

My workflow is to have the agent propose the exact SQL and expected scope, test on a development branch, and deliver a reviewed migration or code change. On Vitess, use the schema workflow described in PlanetScale best practices. Give production write access only for a deliberately chosen operation, then remove it after the work.

Example prompts that produce useful evidence

Give the agent organization, database, branch, engine and an explicit UTC window. PlanetScale recommends placing target names in the project’s agent instructions to avoid repeated discovery calls. That is a targeting hint, not an authorization restriction. Targeting guidance.

For a performance investigation:

For organization acme, database orders, branch main, inspect Insights
for 2026-10-06 09:00–10:00 UTC. Rank query patterns by total time,
then compare their call count and rows read with 08:00–09:00 UTC.
Use metadata and Insights only. Report evidence and missing data;
propose changes without executing SQL.

For an error investigation:

On acme/orders/main, list query error patterns for the incident window.
Inspect executions for the most frequent fingerprint and summarize
the query tags and timing. Separate observed errors from hypotheses.
Do not change the database or request payment-method access.

For a reviewed fix:

Using the branch schema and the slow pattern already identified,
propose an index migration for this engine. Explain what query it
supports and how we will compare performance after deployment.
Prepare a repository diff; do not apply it to production.

These are suggested prompts, not additional server controls. The Insights investigation guide explains how to interpret the evidence, and our production read-access guide covers the broader access decision.

Connecting database evidence to the rest of production

PlanetScale’s server is the database-focused route. Polylane connects to PlanetScale, so when a database problem breaks production it works out why and opens a pull request with the fix, ready for your team’s normal review.

Before calling the setup complete, verify one branch schema request, one Insights request, and the intended absence or restriction of SQL tools. Record the authorization owner so the next incident starts with known access rather than a new permission experiment.

Running on PlanetScale? See how Polylane monitors PlanetScale in production.