> ## Documentation Index > Fetch the complete documentation index at: https://www.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # CockroachDB MCP Server export const InternalLink = ({version, path = "", children, ...props}) => { let detectedVersion = version || "stable"; if (typeof window !== 'undefined' && !version) { const match = window.location.pathname.match(/\/docs\/([^/]+)/); if (match) { detectedVersion = match[1]; } } const normalizedPath = path.startsWith("/") ? path.slice(1) : path; return {children} ; }; The CockroachDB MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets your AI coding tools and AI agents explore live schemas, run queries, and write data on a CockroachDB cluster. The server runs as a local subprocess or a shared HTTP service and exposes a set of typed tools that agents invoke on your behalf. Once connected, you can interact with your cluster using natural language prompts to perform operations such as listing tables, executing `SELECT` statements, and inserting rows. This page explains how the CockroachDB MCP Server works, and what functionality it enables. To learn how to set it up, refer to Install, Configure, and Connect to the CockroachDB MCP Server. For the full list of configuration options, refer to the CockroachDB MCP Server Reference. For CockroachDB Cloud deployments, refer to Connect to the CockroachDB Cloud MCP Server. ## Requirements * An existing CockroachDB cluster with a SQL user whose privileges are suitable for the operations that you want your AI agents to perform. * Installing with `go install` or building from source requires [Go 1.26 or later](https://go.dev/dl/). Alternatively, you can install with pre-built binaries (for Linux and Windows), and a Docker image is also available. ## How it works The server registers a set of [typed MCP tools](#tools) that AI agents invoke on your behalf. These tools trigger SQL queries against the connected cluster using a CockroachDB SQL user. The server supports two transports: * **stdio (default)**: Your AI tool launches the server as a local subprocess and communicates with it over standard input/output. Each user runs their own server instance, authenticated to the cluster with their own SQL credentials. This is the simplest deployment and the recommended starting point. * **HTTP**: The server runs as a long-lived process that multiple MCP clients connect to over HTTPS with a bearer token. This is best for shared or remote deployments. ## Security The server is configured with secure defaults and requires explicit opt-in to relax them. * **Read-only by default.** Unless you explicitly enable write tools with the `CRDB_MCP_ENABLE_WRITE_QUERIES` environment variable, only read tools are registered, and every SQL session is additionally forced read-only with `default_transaction_read_only=true`. For per-operation control, grant the connecting SQL role only the privileges you want: for example, `SELECT`, `INSERT`, and `UPDATE` but not `DELETE` to allow writes without deletes. * **SQL grants are the permission boundary.** Security ultimately comes from what the connecting SQL user is allowed to do in CockroachDB (via `GRANT`), not from which environment variables you set on the MCP server. The server configuration controls which tools are registered, but even with write tools enabled, the SQL user can only do what its grants allow. Least-privilege grants are also the containment for prompt injection: the server cannot distinguish a tool call you intended from one induced by malicious content that the agent has read. * **Password authentication is rejected by default.** In stdio mode the server runs as a subprocess of the AI agent host, which can read passwords from the process environment or `~/.pgpass`. Certificate-based authentication is recommended; password-based authentication requires an explicit opt-in. * **TLS by default, in both directions.** Connections to the cluster require `sslmode` of `require` or stronger, and HTTP mode refuses to start without a TLS certificate and key. Running without TLS—for local development or behind a TLS-terminating reverse proxy—requires explicit opt-in. * **Background quality of service.** By default, queries run at `default_transaction_quality_of_service=background`, so agent traffic does not contend with latency-sensitive foreground workloads. ## Tools For the full tool specifications including parameters, refer to the CockroachDB MCP Server Reference. The server registers the following read-only tools by default: | Tool | Description | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `list_databases` | List all databases in the cluster. | | `list_tables` | List all tables in a database. | | `get_table_schema` | Get the schema for a table, including columns and indexes. | | `get_cluster` | Return cluster identity and version metadata. | | `list_sql_users` | List SQL users defined in the cluster. | | `list_cluster_nodes` | List cluster nodes with address, liveness, and locality. | | `show_running_queries` | List in-flight SQL statements on the cluster. | | `select_query` | Execute a `SELECT` statement. | | `explain_query` | Return the `EXPLAIN` plan for a statement without executing it. | | `show_statement` | Execute a `SHOW` statement such as `SHOW SCHEMAS`, `SHOW INDEXES`, or `SHOW JOBS`. | The following write tools are registered only when `CRDB_MCP_ENABLE_WRITE_QUERIES``=true` is set: | Tool | Description | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | `create_database` | Create a database. | | `create_table` | Execute a `CREATE TABLE` statement. | | `insert_rows` | Execute an `INSERT` statement. | | `update_rows` | Execute an `UPDATE` statement. A `WHERE` clause is mandatory. | | `delete_rows` | Execute a `DELETE` statement. A `WHERE` clause is mandatory. | ## Example usage Use natural language prompts to read from and write to the cluster. You likely do not have to invoke the preceding tools explicitly. Most AI tools should be able to decide which functions to call based on natural language prompts provided by the user. Prompts can be simple, for example: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} List all of the tables in the movr database. ``` They can also be complex and conversational, for example: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} I need to add a reviews table to the movr database so that riders can rate their rides. For the schema, I'm thinking we need: - Review ID (primary key) - Rider reference (foreign key to movr.users) - Ride reference (foreign key to movr.rides) - A 1–5 star rating - Optional text feedback - Timestamp Let's include a secondary index on the rating column. Show me the CREATE TABLE statement so that we can talk it through before you actually create the table. ``` ## See also * Install, Configure, and Connect to the CockroachDB MCP Server * CockroachDB MCP Server Reference * Connect to the CockroachDB Cloud MCP Server * CockroachDB and AI * Agent Skills for CockroachDB * Docs MCP Server