Your agent needs to work with PlanetScale. It needs to inspect a branch schema, run a query against a pull request branch, read Insights to explain a slow query, maybe open a deploy request when a migration is ready. PlanetScale ships a hosted MCP server, general availability since January 2026, and a full REST API that has been production-ready for years. They are not interchangeable, and the dividing line is unusual: the MCP server is built to query and observe a database; the API is built to provision and manage one. Here is how to pick.
You are comparing three surfaces, not two. The MCP server is one object. The API is really a control plane plus a data plane, and the difference matters for agents.
The PlanetScale MCP server is a hosted, remote server at https://mcp.pscale.dev/mcp/planetscale, maintained by PlanetScale and reachable from any client that supports HTTP-hosted MCP over Streamable HTTP. It works for both Vitess (MySQL) and Postgres databases. Queries execute over HTTP through the server, which makes it usable from browser-based tools and sandboxed agents that cannot open a database socket.
It exposes roughly two dozen tools today, weighted toward querying and observability: read and write SQL execution, branch and schema inspection, Query Insights, schema recommendations, query error patterns, query tags, Postgres logs, and billing. The full, current tool list lives in the official PlanetScale MCP server documentation.
The PlanetScale API is a REST management API at api.planetscale.com/v1. Its own documentation is explicit that it does not include direct access to the data in your database; it manages the platform around the data. That surface is broad: databases, branches, deploy requests, backups, passwords and roles, regions, organizations and members, webhooks, audit logs, IP restrictions, and Query Insights reports. You can read the full contract in the PlanetScale API reference.
Because the management API does not run SQL, the direct path to your data is a database connection. For Vitess and MySQL, the Fetch-compatible @planetscale/database serverless driver connects over HTTP using a branch password; for Postgres, PlanetScale supports the Neon serverless driver. Standard wire-protocol clients work too. The credential here is a PlanetScale password scoped to a branch, which is a different secret from the service token or OAuth grant the control plane uses.
The two paths overlap on inspection and Insights, diverge sharply on provisioning, and split cleanly on how you run SQL at volume. The four dimensions below are what actually decide the build.
The table maps agent-relevant capabilities. For SQL execution, the "PlanetScale API" column refers to the database connection described above, not the management API, since the management API does not run queries.
The pattern in the table is the whole story. The MCP server is a read-and-query instrument: it inspects, it profiles, it executes SQL. The moment your agent needs to change the shape of the platform, create a branch, open a deploy request, take a backup, mint a database password, the tools are not there. Those operations live in the API today. PlanetScale is adding MCP tools over time, so treat the boundary as current rather than permanent, but do not design a provisioning agent around tools the server does not yet expose.
This is where PlanetScale departs from most MCP servers, so read carefully rather than assuming the usual OAuth-only story.
The MCP server accepts two credential types. Interactive clients use OAuth 2.1: each client registers dynamically as an OAuth application, the user signs in through the browser, and scopes control access at the organization, database, and branch level. Headless clients export a PlanetScale service token as PLANETSCALE_API_TOKEN and skip the browser entirely, which is what makes CI and background agents viable on the MCP path.
The direct path uses service tokens for the management API, authenticated with an Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN> header and granular per-organization and per-database accesses, plus a branch password for the data plane. OAuth applications are also available when you need users to grant your platform access to their own PlanetScale accounts.
The implication for a multi-tenant agent is concrete. If your product lets each customer connect their own PlanetScale account, every customer is a separate OAuth grant or service token to store, refresh, and revoke. If your agent operates on your own database, the risk shifts from credential sprawl to tool-surface scope, production write access, and per-user audit attribution. Both problems live at the infrastructure layer, not in the choice of path.
The MCP server hands you meaningful safety for free. Each query runs with short-lived, ephemeral credentials that are created on demand and deleted immediately after execution. Read queries route to a replica when one exists, and every statement carries a source=planetscale-mcp comment so you can trace it in Insights. Write safety is built in: unqualified UPDATE and DELETE are blocked, TRUNCATE is blocked, and DDL prompts for human confirmation before it runs. On Postgres, reads run under a role that respects row-level security and warn you when a policy may be filtering results.
The direct path gives you none of that automatically. You own SQL construction, replica routing, retries, the 600 requests per minute management-API rate limit, cursor pagination, and API versioning. That control is exactly what a deterministic pipeline wants: you pin behavior and change it on your schedule rather than absorbing a managed server update mid-run.
Use PlanetScale MCP when:
Use the PlanetScale API directly when:
PlanetScale gives you a strong security posture on the query path. It does not give you the credential lifecycle for your tenant base. That gap is identical whichever path you choose; only the token type changes.
On the MCP path, ephemeral per-query credentials mean the agent never holds a durable database password: the server mints and discards credentials around each execution, and OAuth scopes bound what the connection can see. This is the right default, and it removes a whole class of leaked-credential incidents from the query path.
Neither path is a token vault, a rotation loop, or a revocation flow. A product where customers connect their own PlanetScale accounts accumulates one grant per customer, each needing storage, refresh, and clean revocation when a customer churns. An agent on your own database avoids the sprawl but still needs its tool surface scoped, its production write access controlled, and every action attributed to the user who triggered it. A service token generated months ago and left in an environment variable stays valid until someone remembers to delete it. This is exactly why a token vault is critical for AI agent workflows.
The Scalekit PlanetScale connector wraps the hosted MCP server and vaults each user's grant as a connected account, so credentials never sit in your agent runtime and the same auth infrastructure holds whether your agent leans on the MCP path or calls the API and database directly. The path decision stops being an auth decision.
Scalekit's PlanetScale connector, slug planetscalemcp, is a vendor-MCP connector: it fronts PlanetScale's hosted server with OAuth 2.1 and dynamic client registration, vaults the token, and returns tools your framework can call directly. The examples below use Python and LangChain. The same methods exist in the Node SDK.
Install the SDK and your framework packages, then construct the client from environment credentials found in your Scalekit dashboard.
Resolve the user's connected account and, if it is not active, send them through PlanetScale's OAuth flow once. The authorize a user guide covers production handling of the redirect.
Before the agent runs, load the tools the current connected account is authorized to call. This is the distinction between a per-user agent and a shared-credential one: the surface is derived from what this user granted, not a flat catalog.
The execute_tool call runs one PlanetScale tool under the user's connected account. A read query returns rows without the agent ever holding a database password.
actions.langchain.get_tools() returns native LangChain tools, so the loop is standard: bind the tools, call the model, run each tool call, feed results back until the model stops. The LangChain integration guide has the full walkthrough. For a deeper look at how LangChain tool calling works and where it stops, see our guide on LangChain tool calling.
If you would rather hand your agent an MCP URL than wire tools in code, define a Virtual MCP server that exposes only the PlanetScale tools this agent role needs, then mint a short-lived session token per user and connect over Streamable HTTP.
PlanetScale already secures the query path well. Scalekit addresses the parts that only appear once an agent serves more than one user and touches more than one tool. Recommended reading: MCP authorization for agentic workflows.
Every execute_tool call runs under a specific connected account, and Scalekit records which user, which tool, and which account was involved. That gives you an audit trail tied to the human who authorized the action rather than a shared token, which is exactly what a reviewer wants to see when an agent runs a write query.
Most real agents talk to more than PlanetScale. A Virtual MCP server gives every agent role one static endpoint that declares exactly which connections and tools it can see, while a short-lived session token minted before each run binds the endpoint to a single user's connected accounts. One server definition serves all users; no per-user server configuration, and no credential sharing between tenants.
The hosted PlanetScale server exposes around twenty-five tools. A summarizer that only reads Insights needs a handful of them. Handing an agent the full surface inflates the context window on every run and widens the blast radius if the model misfires. Scoping the surface to the tools a role actually needs cuts token overhead and enforces least privilege, so what the user cannot do, the agent cannot do either. This is a core principle behind production tool-calling auth patterns.
Most production PlanetScale agents will use both surfaces, and the boundary is clean once you see it.
If your agent inspects, queries, or explains a database, build on the MCP path and take the ephemeral credentials and query safeguards that come with it. If your agent provisions the platform or moves data at volume, build on the API and the database connection, where you control versioning, throughput, and lifecycle. The credential management problem is the same either way, and that is the part that needs production-grade infrastructure.
Understanding the difference between MCP and APIs at the architecture level helps clarify why both paths exist and when each one fits.
Read the Scalekit PlanetScale connector docs, see the capabilities on the PlanetScale connector page, or browse the wider developer-tools connectors and full connector catalog. When you are ready to plan a deployment, check pricing.
Building a PlanetScale agent and want a second pair of eyes on the auth model? Join the Scalekit community on Slack, or talk to an engineer for help right away.
