CockroachDB Cloud MCP Server

The CockroachDB Cloud MCP Server is the hosted access from Cockroach Labs through which AI assistants such as Claude Code or Cursor can work with clusters in CockroachDB Cloud. Unlike the local CockroachDB MCP Server for self-managed clusters, you install nothing: the assistant connects over the network to the endpoint https://cockroachlabs.cloud/mcp. This description rests on the vendor's official documentation page; statements about it are accordingly according to the vendor.

What is the CockroachDB Cloud MCP Server?

CockroachDB is a distributed SQL database, and CockroachDB Cloud is its hosted variant. MCP is an open standard through which an assistant calls the tools of an external service. The cloud server translates these calls into operations against your clusters and uses HTTP transport over HTTPS for that. It therefore suits teams that already have Cockroach Labs run their database and do not want to maintain a server of their own.

Which tools are available?

According to the documentation there are nine read tools: list and retrieve clusters, list databases and tables, read a table's schema, run SELECT queries, produce execution plans with EXPLAIN, show statements, and view running queries. In addition there are three write tools: create databases, create tables, and insert rows. Updating or deleting SQL is not named in the tool list.

Sign-in and access rights

There are two ways. OAuth is recommended: you sign in to the CockroachDB Cloud console, choose the organization, and decide whether the assistant may only read, only write, or both. Alternatively you send the secret key of a service account as a bearer token in the Authorization header; then the roles of the service account determine what is allowed. One of the roles Cluster Admin, Cluster Operator, or Cluster Data Accessor is needed on the target clusters. Custom clients additionally have to be allowlisted for their redirect URL by an organization administrator. With an optional mcp-cluster-id header the connection can be limited to a single cluster; calls to other clusters then fail.

What is it particularly useful for?

The value is that an assistant can explore your cloud cluster without anyone distributing connection strings and certificates. It reads the schema, suggests queries, checks them with EXPLAIN, and helps hunt for slow running queries. Because clusters, databases, and tables are reachable through the same endpoint, the server also suits teams with several clusters.

Setup

Register the endpoint in the MCP client as an HTTP server and complete the OAuth sign-in on the first connection. For automation, create a service account with narrow roles and store its key as the bearer token. According to the documentation, start with a staging cluster, because AI tools with access to a cluster can run operations on your behalf.

Security and limits

With OAuth choose read-only access if the assistant should change nothing, and give service accounts the smallest possible role. Limit the connection to one cluster with mcp-cluster-id. Queried data enters the AI client's context and therefore reaches the model provider. The documentation says nothing about a preview status; check the state before production use.

Costs

The documentation page names no separate fee for the MCP server. A prerequisite is a CockroachDB Cloud cluster, whose cost depends on the chosen plan; current terms are on the official Cockroach Labs pricing page. The costs of your AI client come on top.

Who is the CockroachDB Cloud MCP Server for?

It is worthwhile for teams that use CockroachDB Cloud and want to speed up schema work, query analysis, and troubleshooting with an assistant without running a local server. Anyone with self-managed clusters takes the local CockroachDB MCP Server instead. Without a cluster in the cloud this server is of no use.

A CockroachDB Cloud cluster, an account with the role Cluster Admin, Cluster Operator, or Cluster Data Accessor (or a service account with one of these roles), and an MCP client with HTTP support such as Claude Code or Cursor.

With the CockroachDB Cloud MCP Server an AI assistant works with your clusters in CockroachDB Cloud. This guide leads from the role check to the first query.

Step 1: Check the prerequisites

You need a cluster in CockroachDB Cloud and one of the roles Cluster Admin, Cluster Operator, or Cluster Data Accessor on that cluster. You also need an MCP client with HTTP support, such as Claude Code or Cursor. According to the documentation, start with a staging cluster.

Step 2: Register the endpoint

The endpoint is https://cockroachlabs.cloud/mcp. In Claude Code claude mcp add --transport http cockroachdb-cloud https://cockroachlabs.cloud/mcp is enough; in other clients register the address as an HTTP server.

claude mcp add --transport http cockroachdb-cloud https://cockroachlabs.cloud/mcp

Step 3: Sign in with OAuth

On the first call the CockroachDB Cloud console opens. Sign in, choose the organization, and decide whether the assistant may only read, only write, or both. For a start choose read only.

Alternatively use a service account

For automation create a service account with the smallest possible role and send its secret key as a bearer token in the Authorization header. Then the roles of the service account determine what is allowed. Never store the key in the repository.

Limit it to one cluster

With the optional mcp-cluster-id header you limit the connection to a single cluster. Calls that concern another cluster then fail.

Step 4: First queries

Have the clusters listed, choose a database, and ask for the tables and the schema. Then have a query checked with EXPLAIN or show running queries.

Grant write access deliberately

The write tools create databases and tables and insert rows. Grant write access only for staging clusters and review every suggestion of the assistant before you confirm it.

OAuth through the CockroachDB Cloud console (recommended) or a service account secret key as a bearer token in the Authorization header.

With OAuth you choose read, write, or both; with API keys the roles of the service account apply. Optionally limitable to one cluster with the mcp-cluster-id header.

The server is hosted by Cockroach Labs. Queried data enters the AI client context and therefore reaches the model provider.

Unwanted writes when write access is granted or service account roles are too broad, passing business data to the model provider, and openly stored API keys.