CockroachDB MCP Server Reference

This page lists the configuration options for the that connects to self-hosted CockroachDB deployments. To set up the server, refer to .

Configuration

All configuration is managed via environment variables. In stdio mode, set them in the env block of your MCP client configuration; in HTTP mode, export them in the server’s environment.

Authentication

Certificate-based authentication is recommended in stdio mode. The server runs as a subprocess of the AI agent host, which can read CRDB_PWD, a password embedded in CRDB_DATABASE_URL, PGPASSWORD, or ~/.pgpass from the process’s environment. To protect those credentials, password-based authentication is rejected by default; set CRDB_MCP_ALLOW_PASSWORD_AUTH=true to opt in. You can authenticate with individual variables (recommended) or with a full connection string. CRDB_DATABASE_URL takes precedence when both are set.

Variable	Description	Required	Default
`CRDB_HOST`	Hostname. For a multi-node cluster, use a load balancer address; for development, any node’s address.	Yes
`CRDB_PORT`	Port.	No	`26257`
`CRDB_USERNAME`	SQL user.	Yes
`CRDB_PWD`	Password. Requires `CRDB_MCP_ALLOW_PASSWORD_AUTH=true`. Certificate-based authentication is recommended instead.	No
`CRDB_SSL_MODE`	`require`, `verify-ca`, or `verify-full`. TLS-optional modes (`disable`, `allow`, `prefer`) require `CRDB_MCP_ALLOW_INSECURE_DB=true`.	No	`verify-full`
`CRDB_SSL_CA_PATH`	CA certificate path.	When `CRDB_SSL_MODE` is `verify-ca` or `verify-full` (the default)
`CRDB_SSL_CERTFILE`	Client certificate path.	When `CRDB_SSL_MODE` is `require`, `verify-ca`, or `verify-full` (the default)
`CRDB_SSL_KEYFILE`	Client key path.	When `CRDB_SSL_MODE` is `require`, `verify-ca`, or `verify-full` (the default)

Alternatively, use a full connection string:

Variable	Description
`CRDB_DATABASE_URL`	A full libpq connection string (for example, `postgresql://user@host:26257/defaultdb?sslmode=verify-full&sslcert=...`). When set, the individual variables above are ignored. A `CRDB_DATABASE_URL` that omits `sslmode` is rejected at startup.

Query behavior

Variable	Description	Required	Default
`CRDB_MCP_QUERY_TIMEOUT`	Per-query timeout, as a Go duration (for example, `30s`). The server cancels a query that exceeds it.	No	`30s`
`CRDB_MCP_MAX_ROWS_COUNT`	Cap on the maximum `LIMIT` that list-style tools issue to CockroachDB.	No	`10000`
`CRDB_MCP_MAX_CONNS`	Upper bound on the connection pool size (up to 100).	No	`10`
`CRDB_MCP_TXN_QOS`	Default transaction quality of service: `background`, `regular`, or `critical`. Refer to the precedence notes below the table.	No	`background`
`CRDB_MCP_ENABLE_WRITE_QUERIES`	Enable the write tools. For per-operation control, grant the connecting role only the SQL privileges you want, for example `SELECT`, `INSERT`, and `UPDATE` but not `DELETE` to allow writes without deletes.	No	`false`
`CRDB_MCP_ALLOW_PASSWORD_AUTH`	Opt in to password-based authentication. The server refuses to start if a password is detected from any source (`CRDB_PWD`, a password in `CRDB_DATABASE_URL`, `PGPASSWORD`, or `~/.pgpass`) unless this is set to `true`.	No	`false`
`CRDB_MCP_ALLOW_INSECURE_DB`	Opt in to the `sslmode` values that can run without TLS: `disable`, `allow`, `prefer`. Certificate variables are not required in these modes. Development only.	No	`false`

MCP traffic runs at default_transaction_quality_of_service=background by default, so it does not contend with latency-sensitive foreground workloads. The value is chosen with the following precedence:

CRDB_MCP_TXN_QOS, if set (background, regular, or critical).
Otherwise, a default_transaction_quality_of_service=... query parameter in CRDB_DATABASE_URL, if present.
Otherwise, background.

Transport

Variable	Description	Required	Default
`CRDB_MCP_TRANSPORT`	`stdio` or `http`.	No	`stdio`
`CRDB_MCP_HTTP_LISTEN_ADDR`	Listen address in HTTP mode, any `host:port`. Omit the host to bind all interfaces. Examples: `:8080`, `0.0.0.0:8443`, `127.0.0.1:9090`.	No	`:8080`
`CRDB_MCP_BEARER_TOKEN`	Bearer token that clients must send in `Authorization: Bearer {token}`. Must be at least 16 characters.	Required for `http` mode, unless `CRDB_MCP_ALLOW_NO_BEARER=true`
`CRDB_MCP_TLS_CERT`	PEM-encoded server certificate path.	Required for `http` mode, unless `CRDB_MCP_ALLOW_INSECURE_HTTP=true`
`CRDB_MCP_TLS_KEY`	PEM-encoded private key path.	Required for `http` mode, unless `CRDB_MCP_ALLOW_INSECURE_HTTP=true`
`CRDB_MCP_ALLOW_INSECURE_HTTP`	Opt in to cleartext HTTP (for reverse-proxy deployments).	No	`false`
`CRDB_MCP_ALLOW_NO_BEARER`	Opt in to skipping bearer authentication (for upstream-auth deployments). A startup warning is logged. Mutually exclusive with `CRDB_MCP_BEARER_TOKEN`: the server refuses to start if both are set.	No	`false`

Logging

Variable	Description	Required	Default
`CRDB_MCP_LOG_LEVEL`	`debug`, `info`, `warn`, or `error`.	No	`info`
`CRDB_MCP_LOG_PATH`	Log file path, or `-` for stderr. No rotation; use logrotate or your orchestrator.	No

Tracing (OpenTelemetry)

Tracing is opt-in. When neither of the following variables is set, no exporter is installed. When enabled, tool calls and their SQL statements are exported as spans, and server logs are exported as OpenTelemetry log records. Query text and errors are redacted before export, so literals and user data never leave the server.

Variable	Description	Required
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP gRPC endpoint; the standard `OTEL_*` environment variables are honored.	No
`CRDB_MCP_OTEL_FILE`	Write traces and logs as JSON lines to this file instead (takes precedence).	No

Tools

The following sections list the tools that the MCP server makes available to agents. You likely do not have to invoke these functions explicitly. Most AI tools should be able to decide which functions to call based on natural language prompts provided by the user.

Read-only tools

The following tools are registered by default. They do not modify cluster data.

`list_databases`

List all databases in the cluster.

Parameter	Description	Type	Required	Default
`limit`	Maximum rows to return, capped at `CRDB_MCP_MAX_ROWS_COUNT`.	integer	No	`100`
`offset`	Rows to skip before returning results.	integer	No	`0`

`list_tables`

List all tables in a database.

Parameter	Description	Type	Required	Default
`database`	Database whose tables are listed.	string	Yes
`limit`	Maximum rows to return, capped at `CRDB_MCP_MAX_ROWS_COUNT`.	integer	No	`100`
`offset`	Rows to skip before returning results.	integer	No	`0`

`get_table_schema`

Get detailed schema information for a table, including columns and indexes. Returns the statement.

Parameter	Description	Type	Required	Default
`database`	Database containing the table.	string	Yes
`table`	Table name.	string	Yes
`schema`	Schema name.	string	No	`public`

`get_cluster`

Return cluster identity and version metadata: cluster_id, cluster_name, binary_version, active_version. The identity fields (cluster_id, cluster_name, and active_version) require access to crdb_internal built-in functions, which are gated by default on CockroachDB v25.4 and later. When these fields cannot be accessed, they are returned as null, with the reason reported under an unavailable key. binary_version is always returned. This tool takes no parameters.

`list_sql_users`

List SQL users defined in the cluster.

Parameter	Description	Type	Required	Default
`limit`	Maximum rows to return, capped at `CRDB_MCP_MAX_ROWS_COUNT`.	integer	No	`100`
`offset`	Rows to skip before returning results.	integer	No	`0`

`list_cluster_nodes`

List cluster nodes with address, liveness, and locality. Requires admin or the VIEWCLUSTERMETADATA . This tool takes no parameters.

`show_running_queries`

List in-flight SQL statements on the cluster, ordered by start time descending. Viewing other users’ statements requires admin or the VIEWACTIVITY or VIEWACTIVITYREDACTED ; otherwise, only the connecting user’s own statements are returned.

Parameter	Description	Type	Required	Default
`limit`	Maximum rows to return, capped at `CRDB_MCP_MAX_ROWS_COUNT`.	integer	No	`100`
`offset`	Rows to skip before returning results.	integer	No	`0`

`select_query`

Execute a single statement. Non-SELECT statements are rejected. A default LIMIT of 100 is appended when none is supplied, capped at CRDB_MCP_MAX_ROWS_COUNT. An explicit LIMIT that exceeds CRDB_MCP_MAX_ROWS_COUNT, or LIMIT ALL, is rejected.

Parameter	Description	Type	Required
`query`	A single `SELECT` statement.	string	Yes

`explain_query`

Return the plan for a single SQL statement without executing it. EXPLAIN ANALYZE (and EXPLAIN ANALYZE (DEBUG)) is rejected because it executes the statement. Display options (VERBOSE, DISTSQL, TYPES, OPT, and so on) pass through.

Parameter	Description	Type	Required
`query`	A single SQL statement.	string	Yes

`show_statement`

Execute a single SHOW statement such as SHOW SCHEMAS, SHOW INDEXES, SHOW REGIONS, or SHOW JOBS. A default LIMIT is appended, capped at CRDB_MCP_MAX_ROWS_COUNT.

Parameter	Description	Type	Required	Default
`query`	A single `SHOW` statement.	string	Yes
`limit`	Maximum rows to return, capped at `CRDB_MCP_MAX_ROWS_COUNT`.	integer	No	`100`
`offset`	Rows to skip before returning results.	integer	No	`0`

Write tools

The following tools are registered only when CRDB_MCP_ENABLE_WRITE_QUERIES=true is set. Any write tool that includes a RETURNING clause returns the affected rows instead of just the count.

`create_database`

Create a database.

Parameter	Description	Type	Required	Default
`name`	Database name to create.	string	Yes
`if_not_exists`	When `true`, the statement is a no-op if the database already exists.	boolean	No	`false`

`create_table`

Execute a single statement.

Parameter	Description	Type	Required
`statement`	A single `CREATE TABLE` statement. Qualify the table with a database when not using the connection’s default database.	string	Yes

`insert_rows`

Execute a single statement. Returns the number of rows affected.

Parameter	Description	Type	Required
`statement`	A single `INSERT` statement. A `RETURNING` clause returns the inserted rows. Qualify the table with a database when not using the connection’s default database.	string	Yes

`update_rows`

Execute a single statement. A WHERE clause is mandatory. Returns the number of rows affected.

Parameter	Description	Type	Required
`statement`	A single `UPDATE` statement. A `WHERE` clause is mandatory. A `RETURNING` clause returns the updated rows. Qualify the table with a database when not using the connection’s default database.	string	Yes

`delete_rows`

Execute a single statement. A WHERE clause is mandatory. Returns the number of rows affected.

Parameter	Description	Type	Required
`statement`	A single `DELETE` statement. A `WHERE` clause is mandatory. A `RETURNING` clause returns the deleted rows. Qualify the table with a database when not using the connection’s default database.	string	Yes

Get Started

CockroachDB and AI

Feature Overview

Data Resilience

Connect to an Application

Self-Hosted Deployments

Schema Design

Reads and Writes

Stream Data

Cross-Cluster Replication

Multi-Region Capabilities

Optimize Performance

Integrate

CockroachDB MCP Server Reference

Configuration

Authentication

Query behavior

Transport

Logging

Tracing (OpenTelemetry)

Tools

Read-only tools

`list_databases`

`list_tables`

`get_table_schema`

`get_cluster`

`list_sql_users`

`list_cluster_nodes`

`show_running_queries`

`select_query`

`explain_query`

`show_statement`

Write tools

`create_database`

`create_table`

`insert_rows`

`update_rows`

`delete_rows`

See also

​Configuration

​Authentication

​Query behavior

​Transport

​Logging

​Tracing (OpenTelemetry)

​Tools

​Read-only tools

​list_databases

​list_tables

​get_table_schema

​get_cluster

​list_sql_users

​list_cluster_nodes

​show_running_queries

​select_query

​explain_query

​show_statement

​Write tools

​create_database

​create_table

​insert_rows

​update_rows

​delete_rows

​See also

Configuration

Authentication

Query behavior

Transport

Logging

Tracing (OpenTelemetry)

Tools

Read-only tools

`list_databases`

`list_tables`

`get_table_schema`

`get_cluster`

`list_sql_users`

`list_cluster_nodes`

`show_running_queries`

`select_query`

`explain_query`

`show_statement`

Write tools

`create_database`

`create_table`

`insert_rows`

`update_rows`

`delete_rows`

See also