CockroachDB MCP Server Cursor IDE Setup 2026: Cloud Endpoint & Self-Hosted

How do you set up the CockroachDB MCP server in Cursor? For CockroachDB Cloud clusters, add a cockroachdb entry under mcpServers in mcp.json pointed at the managed endpoint https://cockroachlabs.cloud/mcp, with an mcp-cluster-id header identifying your cluster and a service-account API key as an Authorization: Bearer token. For a self-hosted cluster, run the open-source server locally over stdio, or as a Streamable HTTP service, with connection details pointing at your own CockroachDB instance. Either path gives Cursor's agent the ability to inspect live schemas, list tables, and run read-only SQL against a real cluster — read-only by default, with writes behind an explicit opt-in.

Cockroach Labs publishes two distinct things under "CockroachDB MCP server," and conflating them is the most common setup mistake: a fully managed endpoint for CockroachDB Cloud clusters that Cockroach Labs hosts and secures, and a self-hosted, open-source server you run yourself against any CockroachDB cluster, cloud or on-prem. This guide covers both, since which one applies depends entirely on whether your cluster is on CockroachDB Cloud.

CockroachDB is PostgreSQL wire-compatible, so if you're coming from Postgres tooling, the PostgreSQL MCP server guide covers the adjacent non-distributed case. For other managed SQL platforms with their own MCP servers, see PlanetScale and Neon.

Which server do you actually need?

CockroachDB Cloud, managed endpoint. If your cluster runs on CockroachDB Cloud (formerly CockroachCloud), Cockroach Labs already operates the MCP server for you at cockroachlabs.cloud/mcp. There's no process to run, no Docker image to pull, and no infrastructure on your end — a single config snippet from the Cloud Console is the entire setup. This is the right default for anyone on the managed platform.

Self-hosted, open source. If you run CockroachDB yourself — on your own VMs, in Kubernetes, or anywhere outside CockroachDB Cloud — there's no managed endpoint for your cluster. You run the open-source cockroachdb-mcp-server yourself, either as a local stdio subprocess Cursor launches per session, or as a shared HTTP service. It connects to your cluster the same way any SQL client would: a connection string and a database user.

Both expose broadly the same class of tools — schema inspection, SQL execution, cluster status — but the exact tool list and the auth model differ, covered separately below.

Method 1: CockroachDB Cloud managed endpoint (recommended for Cloud clusters)

What it exposes

Cockroach Labs' blog on the managed endpoint describes the tool set as covering schema exploration, query execution, and query-plan inspection — listing databases and tables, describing schemas and indexes, inspecting cluster health, and running queries. Read-only mode is the default; write access (creating databases, creating tables, inserting rows) requires explicit enablement and consent, mirroring the self-hosted server's write gate described below.

Authentication

The managed endpoint supports two auth modes: OAuth 2.0 for interactive human workflows (the Cloud Console walks you through this when generating a config snippet), and service-account API keys for automated or pipeline use where an interactive browser login isn't practical. For a Cursor setup, a service-account key is usually the simpler path since it doesn't require a browser popup mid-session.

Cursor config

Generate a service account API key from the CockroachDB Cloud Console, then add:

{
  "mcpServers": {
    "cockroachdb": {
      "url": "https://cockroachlabs.cloud/mcp",
      "headers": {
        "mcp-cluster-id": "YOUR_CLUSTER_ID",
        "Authorization": "Bearer YOUR_SERVICE_ACCOUNT_API_KEY"
      }
    }
  }
}

mcp-cluster-id is how the managed endpoint knows which of your clusters a given call targets — without it, or with the wrong ID, calls will fail or, worse, silently target a cluster you didn't mean to query. Copy the cluster ID directly from the Cloud Console rather than guessing at its format.

Restart Cursor and confirm a green cockroachdb entry in Settings → MCP.

Why the managed path is worth defaulting to on Cloud

Because Cockroach Labs operates this endpoint directly, it integrates with your cluster's existing Cloud authentication and RBAC rather than needing a separately managed SQL user and password. There's nothing to patch, restart, or keep running on your side — the tradeoff most self-hosted MCP servers carry.

Method 2: Self-hosted server (any cluster, including on-prem)

Prerequisites

stdio config

{
  "mcpServers": {
    "cockroachdb": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "CRDB_MCP_CONNECTION_STRING",
        "cockroachdb/cockroachdb-mcp-server"
      ],
      "env": {
        "CRDB_MCP_CONNECTION_STRING": "postgresql://mcp_user@localhost:26257/defaultdb?sslmode=verify-full&sslrootcert=/certs/ca.crt&sslcert=/certs/client.mcp_user.crt&sslkey=/certs/client.mcp_user.key"
      }
    }
  }
}

CockroachDB's wire protocol is Postgres-compatible, so the connection string shape matches what you'd use with any Postgres client — the sslmode=verify-full plus certificate paths is what "certificate-based authentication" means in practice here. Mount your certs directory into the container if you're running this via Docker, since the paths in the connection string need to resolve inside the container, not just on your host.

Enabling write access

By default, the self-hosted server registers only read tools, and forces default_transaction_read_only=true on every SQL session it opens — a belt-and-suspenders read-only guarantee that holds even if a read tool's query somehow tried to write. To enable the write-capable tools, set CRDB_MCP_ENABLE_WRITE_QUERIES=true in the same env block used for the connection string. Don't flip this on for a connection pointed at a production cluster without a specific reason — the default exists because most schema-exploration and debugging use cases genuinely don't need write access.

Streamable HTTP mode

For a shared instance rather than a per-session subprocess, run the server as an HTTP service and point Cursor at its URL instead of a command, the same pattern used by most other remote MCP servers on this site:

{
  "mcpServers": {
    "cockroachdb": {
      "url": "https://cockroach-mcp.internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_SERVICE_TOKEN"
      }
    }
  }
}

The exact header your self-hosted HTTP deployment expects depends on how you've fronted it — if you're putting it behind your own reverse proxy, that proxy's auth requirements apply here, not a Cockroach Labs-defined header, since this is your own deployment rather than a Cockroach Labs-operated service.

Tools exposed by the self-hosted server

Read-only, registered by default:

Write tools, registered only when CRDB_MCP_ENABLE_WRITE_QUERIES=true:

There's no drop_table or drop_database in the documented write set — destructive schema changes stay outside what this server will do even with write mode enabled, which is a reasonable line to draw for an AI-driven connection.

Practical workflows

Understanding an unfamiliar schema before writing a migration:

List the tables in the orders database, then show me the schema for the orders and order_items tables so I understand the foreign key relationships before I write a migration.

Diagnosing a slow query:

Run EXPLAIN on this query and tell me whether it's using the index I expect: SELECT * FROM orders WHERE customer_id = $1 AND status = 'pending'

Checking cluster health during an incident:

List the cluster nodes and their status, then show me any currently running queries that have been executing for more than 30 seconds.

Read-write example, only with write mode enabled and after review:

Insert a test row into the staging_events table matching this shape: {event_type: "test", payload: {}, created_at: now()}

Cursor prompts for approval before write tools run by default. Approve select_query, explain_query, and the list/describe tools freely — they can't change data. Read the arguments before approving insert_rows, update_rows, or delete_rows, especially against anything that isn't a scratch or staging database.

Distributed SQL gotchas that don't show up on a single-node Postgres box

CockroachDB is a distributed database, and a couple of things behave differently from a single-node Postgres instance in ways that matter when an AI agent is generating queries against it:

Range splits affect query plans on large tables. EXPLAIN output on a table with billions of rows spread across many ranges can look different from what you'd expect on Postgres — a plan that looks inefficient at first glance may actually be CockroachDB correctly parallelizing across ranges. Don't assume the agent's read of an unfamiliar EXPLAIN output transfers directly from Postgres intuition.

Contention shows up as retryable transaction errors, not deadlocks. CockroachDB's serializable isolation means write conflicts under load surface as a transaction that needs client-side retry, not a deadlock in the Postgres sense. If insert_rows or update_rows fails with a retry-class error under concurrent load, that's often expected behavior for the isolation level, not a bug in the query.

Multi-region clusters add locality to EXPLAIN output. If your cluster spans regions, query plans reference which region data lives in — worth having the agent surface that detail when a query is slower than expected, since cross-region reads carry real latency that a single-node mental model won't predict.

Troubleshooting

Managed endpoint: "cluster not found" or similar. The mcp-cluster-id header is missing, wrong, or belongs to a cluster the service account doesn't have access to. Copy the exact ID from the CockroachDB Cloud Console rather than reconstructing it from the cluster name.

Managed endpoint: 401 on every call. The service-account API key is expired, revoked, or was generated for a different organization than the cluster belongs to. Regenerate from the Cloud Console.

Self-hosted: connection refused. Confirm the connection string's host and port are reachable from wherever the server process actually runs — inside a Docker container, localhost refers to the container's own network namespace, not your host machine. Use host.docker.internal (Docker Desktop) or the cluster's real address instead.

Self-hosted: certificate errors. sslmode=verify-full requires the CA cert, client cert, and client key paths to all resolve inside wherever the server process runs. If you're using Docker, the cert directory needs to be mounted as a volume — a connection string pointing at host-machine cert paths will fail inside the container even if those files exist on your host.

Write tools don't appear even though I set the env var. Confirm CRDB_MCP_ENABLE_WRITE_QUERIES is spelled exactly right and set on the same mcpServers entry actually being used — a typo'd variable name is silently ignored rather than raising a startup error on most MCP servers that read config this way.

Queries fail with a serialization or retry error under load. This is expected CockroachDB behavior under contention with serializable isolation, not a broken connection — see the distributed SQL gotchas above. Retrying the specific transaction, rather than assuming the connection is unstable, is the correct response.

When not to use write mode

Don't enable CRDB_MCP_ENABLE_WRITE_QUERIES on a connection pointed at a production cluster inside a fully autonomous agent loop with no human review step. An agent confidently running insert_rows or update_rows based on a misread schema is a bad way to discover a data-quality issue — keep write mode scoped to a scratch database, a staging cluster, or sessions where you're reviewing every write tool call before it runs.

Frequently Asked Questions

Is there an official CockroachDB MCP server, or only third-party ones?
Both exist. Cockroach Labs operates a fully managed endpoint for CockroachDB Cloud clusters at cockroachlabs.cloud/mcp, and separately publishes an open-source, self-hosted server for any CockroachDB cluster. Third-party community servers also exist on GitHub, but the two covered in this guide are the Cockroach Labs-published options.

Do I need the managed endpoint, or the self-hosted server?
If your cluster runs on CockroachDB Cloud, the managed endpoint requires no infrastructure on your side — just a cluster ID and an API key. If you run CockroachDB yourself outside Cloud, there's no managed endpoint for your cluster, so you run the self-hosted open-source server against your own connection string instead.

Is write access on by default?
No, on both paths. The self-hosted server registers only read tools and forces default_transaction_read_only=true on every session unless CRDB_MCP_ENABLE_WRITE_QUERIES=true is set. The managed Cloud endpoint is read-only by default with write access requiring explicit opt-in and consent.

Can this server drop a table or database?
No. The documented write tool set covers create_database, create_table, insert_rows, update_rows, and delete_rows — there's no destructive schema-drop tool in either the managed or self-hosted tool list.

Does authentication differ between the two setup methods?
Yes. The managed Cloud endpoint uses OAuth 2.0 for interactive use or a service-account API key for automated use, sent as a bearer token alongside an mcp-cluster-id header. The self-hosted server uses certificate-based authentication by default against your own cluster's SQL user; password authentication is rejected unless explicitly enabled.

Related Guides

Official docs cited