> ## 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 Reference
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}
;
};
This page lists the configuration options for the MCP Server that connects to self-hosted CockroachDB deployments. To set up the server, refer to Install, Configure, and Connect to the CockroachDB MCP Server.
## 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`](#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`](#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`](#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`](#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](#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`](#crdb-pwd), a password in [`CRDB_DATABASE_URL`](#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:
1. [`CRDB_MCP_TXN_QOS`](#crdb-mcp-txn-qos), if set (`background`, `regular`, or `critical`).
2. Otherwise, a `default_transaction_quality_of_service=...` query parameter in [`CRDB_DATABASE_URL`](#crdb-database-url), if present.
3. 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`](#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`](#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`](#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`](#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`](#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`](#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 `CREATE TABLE` 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`](#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` system privilege.
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` system privilege; 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`](#crdb-mcp-max-rows-count). | integer | No | `100` |
| `offset` | Rows to skip before returning results. | integer | No | `0` |
#### `select_query`
Execute a single `SELECT` statement. Non-`SELECT` statements are rejected. A default `LIMIT` of `100` is appended when none is supplied, capped at [`CRDB_MCP_MAX_ROWS_COUNT`](#crdb-mcp-max-rows-count). An explicit `LIMIT` that exceeds [`CRDB_MCP_MAX_ROWS_COUNT`](#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 `EXPLAIN` 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`](#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`](#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`](#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 `CREATE TABLE` 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 `INSERT` 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 `UPDATE` 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 `DELETE` 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 |
## See also
* CockroachDB MCP Server
* Install, Configure, and Connect to the CockroachDB MCP Server
* [CockroachDB MCP Server on GitHub](https://github.com/cockroachdb/cockroachdb-mcp-server)