PlanetScale Model Context Protocol (MCP)

​

What is the PlanetScale MCP server?

• A hosted MCP server that exposes your PlanetScale organizations, databases, branches, schema, and Insights data to MCP-compatible tools.
• Authenticated via OAuth for configurable access to permissions and scopes.
• Accessible from any MCP client that supports HTTP-hosted servers.

​

Quick start

​

Authentication

• Each client (for example, Claude Code, Cursor, or other MCP-compatible tools) registers as an OAuth application with PlanetScale.
• When you connect the MCP server from your client, you’re redirected to PlanetScale to sign in and grant access.

https://mcp.pscale.dev/mcp/planetscale

​

Security and credentials

• Each query uses short-lived, ephemeral credentials that are created on demand and deleted immediately after execution.

​

Scopes and permissions

• Scopes define which organizations, databases, branches, or features the MCP server can see.
• You choose whether the MCP server has no access, read-only access, or full access to databases at the organization or per-database level.

​

Installation instructions

​

Cursor

1. Open the command palette and type “Cursor Settings”
2. Under “Tools & MCP” click “New MCP Server”
3. Paste the following JSON into the configuration file that opens

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

4. Once this configuration is saved, Cursor will attempt to authenticate and show a login prompt. Select this prompt to grant Cursor access to your PlanetScale account.
5. You may need to restart Cursor to load the new configuration.

​

VS Code

1. Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS)
2. Type “MCP: Add Server”
3. Choose “HTTP”
4. Enter the following details:
   • URL: https://mcp.pscale.dev/mcp/planetscale
   • Name: “PlanetScale”
5. Click “Add”

1. Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS)
2. Type “MCP: List Servers”
3. Select “PlanetScale”
4. Click “Start Server”
5. When the dialog appears saying “The MCP Server Definition ‘PlanetScale’ wants to authenticate to PlanetScale MCP,” click “Allow”
6. A popup will ask “Do you want Code to open the external website?” — click “Cancel”
7. You’ll see a message: “Having trouble authenticating to ‘PlanetScale MCP’? Would you like to try a different way? (URL Handler)”
8. Click “Yes”
9. Click “Open” and complete the PlanetScale sign-in flow to connect to PlanetScale MCP

​

OpenCode

1. Ensure OpenCode is installed and available in your terminal

opencode --version

2. Add the PlanetScale MCP server to your OpenCode configuration file.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "planetscale": {
      "type": "remote",
      "url": "https://mcp.pscale.dev/mcp/planetscale"
    }
  }
}

3. Enter the following to authenticate with the PlanetScale MCP server

opencode mcp auth planetscale

4. Enter OpenCode

opencode

5. List the available MCP servers with the /mcp slash command.

/mcp

planetscale connected

​

Claude.ai and Claude for desktop

1. Navigate to Settings > Connectors
2. Click Add custom connector at the bottom of the section
3. Enter the PlanetScale MCP server URL: https://mcp.pscale.dev/mcp/planetscale
4. Click Add to save the connector
5. Follow the prompts to authenticate with your PlanetScale account

1. Click the + button in the lower left of your chat interface
2. Select Connectors
3. Toggle the PlanetScale connector on for that conversation

​

Claude Code

1. Ensure Claude Code is available in your terminal

claude --version

2. Run the following command to add the PlanetScale MCP server to your Claude Code

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

3. Enter Claude Code

claude

4. List the available MCP servers with the /mcp slash command.

/mcp

❯ planetscale · △ needs authentication

❯ /mcp
  ⎿  Authentication successful. Connected to planetscale.

​

Gemini CLI

1. Ensure Gemini CLI is available in your terminal

gemini --version

2. Run the following command to add the PlanetScale MCP server to your Gemini CLI

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

3. Enter Gemini CLI

gemini

4. List the available MCP servers with the /mcp slash command and select “List”

/mcp list

🔴 planetscale - Disconnected (OAuth not authenticated)

/mcp auth planetscale

ℹ ✅ Successfully authenticated with MCP server 'planetscale'!

​

Codex CLI

1. Ensure Codex CLI is available in your terminal

codex --version

2. Run the following command to add the PlanetScale MCP server to your Codex CLI

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

3. Enter Codex CLI

codex

4. List the available MCP servers with the /mcp slash command

/mcp

• planetscale
  • Status: enabled
  • Auth: OAuth

​

Amp CLI

1. Ensure Amp CLI is available in your terminal

amp --version

2. Run the following command to add the PlanetScale MCP server to your Amp CLI

amp mcp add planetscale https://mcp.pscale.dev/mcp/planetscale

3. Enter Amp CLI

amp

4. You should be immediately prompted to authenticate. Follow the instructions in the browser.
5. List the available MCP servers with the /mcp list tools command.

/mcp list tools

​

Query handling

​

Read queries

• Read queries automatically use a replica when your database has replicas configured, reducing load on the primary.
• All queries include a source=planetscale-mcp comment, making them easy to identify and track in Insights.

​

Write query safeguards

• UPDATE or DELETE statements without a WHERE clause are blocked.
• TRUNCATE statements are blocked.
• DDL statements (CREATE, DROP, ALTER, etc.) prompt the LLM to request human confirmation before proceeding.

​

Example workflows

• “Show me all databases in my PlanetScale organization and highlight anything running on PlanetScale Metal.”
• “List the branches for my production database and summarize their differences.”
• “Look at my slowest queries over the last day and suggest index or query changes.”
• “Check whether the CPU and memory profile for my database is appropriate for the current workload.”
• “Explain what changed between yesterday’s and today’s query patterns in Insights.”

​

Available tools

1. planetscale_list_organizations - List all PlanetScale organizations you have access to.
2. planetscale_list_databases - List all databases within an organization.
3. planetscale_list_branches - List all branches within a database.
4. planetscale_get_organization - Get details about a specific organization.
5. planetscale_get_database - Get details about a specific database.
6. planetscale_get_branch - Get details about a database branch.
7. planetscale_get_branch_schema - Get the schema for a database branch.
8. planetscale_execute_read_query - Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN) against a PlanetScale database.
9. planetscale_execute_write_query - Execute a write SQL query (INSERT, UPDATE, DELETE, or DDL) against a PlanetScale database.
10. planetscale_get_insights - Get query performance insights for a PlanetScale database branch.
11. planetscale_list_regions_for_organization - List all available regions for an organization.
12. planetscale_list_cluster_size_skus - List all available cluster size SKUs.
13. planetscale_list_invoices - List all invoices for an organization.
14. planetscale_get_invoice_line_items - Get all line items for an invoice, with prorated costs broken down by database branch.
15. planetscale_search_documentation - Search the PlanetScale documentation.

​

Troubleshooting

1. Restart your client or CLI tool After installation, you may need to restart your client or CLI tool to load the new MCP configuration.
2. Check the server URL Make sure the MCP server URL is set to the hosted endpoint (for example, https://mcp.pscale.dev/mcp/planetscale).
3. Re-authorize the MCP server If scopes or tokens have changed, reauthorize the PlanetScale MCP server in your client so it can request fresh tokens.
4. Verify organization and database access Confirm that your PlanetScale user account has access to the orgs and databases you expect to see.

​

PlanetScale CLI MCP server

​

Need help?