Connect to the CockroachDB Cloud MCP Server

CockroachDB Cloud includes a managed Model Context Protocol (MCP) server that enables your AI coding tools and AI agents to access the clusters in your CockroachDB Cloud organization. Your AI tools can explore live schemas and run queries against any cluster using OAuth or API key authentication. A user can interact with their clusters using natural language prompts to perform read and write operations such as listing tables, executing statements, and inserting rows into a table. By default, a single MCP server connection provides access to all clusters in the organization that the user or service account has permission to access. You can optionally restrict a connection to one cluster, to limit your AI tool’s access. This page explains how to connect your AI tools to the CockroachDB Cloud MCP server, including detailed instructions for the following tools:

Claude Code
Cursor
Cline
GitHub Copilot
Codex

To connect a custom or enterprise MCP client using OAuth, you may also need to allowlist its redirect URL.

AI tools with cluster access can execute operations on your behalf. When first connecting an AI tool to CockroachDB, consider starting with a staging cluster to understand the tool’s behavior before granting it access to production data.

Before you begin

.
If you plan to connect to the MCP server using OAuth, ensure that the user managing the MCP server connection to the Cloud Console. Ensure that the user has been assigned the , , or role on the clusters that you want the MCP server connection to access.
- If you plan to connect a custom or enterprise MCP client using OAuth, ensure that the client’s redirect URL has been allowlisted by an .
If you plan to connect to the MCP server using an API key, create a and an in the CockroachDB Cloud Console. Ensure that the service account has been assigned the , , or role on the clusters that you want the MCP server connection to access.
- Copy the secret key that’s generated upon service account creation.

Connect to the MCP server

Step 1. Choose your authentication method

Cockroach Labs recommends using OAuth to connect to the Cloud MCP server, as short-lived tokens are more secure than long-lived tokens. Select an option:

OAuth
API Key

Step 2. Choose your cluster scope

By default, an MCP server connection can access every cluster in the organization that your user has permission to access. If you want to prevent your AI tool from switching between clusters, you can scope the connection to a single cluster. Single cluster configurations add an mcp-cluster-id header: when this header is set, all MCP tools will operate on that cluster, and tool calls that pass in a different cluster_id will fail with an error.If you choose to limit your connection to a single cluster, find your Cluster ID in the URL of the cluster’s : https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview.Select an option:

All clusters
Single cluster

Step 3. Update tool configuration

Cockroach Labs enables access to its CockroachDB Cloud MCP server via HTTP transport (using HTTPS).Different AI tools might have slightly different ways of connecting to an MCP server via HTTP. This will normally involve adding a JSON snippet to a configuration file, which will include:

The MCP server URL: https://cockroachlabs.cloud/mcp

The specific JSON snippet might look slightly different for each tool, and the tool might offer CLI commands to simplify the configuration process.The following are instructions for how to update the configuration of some common AI tools. For other tools, read the documentation for those tools.

Claude Code
Cursor
Cline
GitHub Copilot
Codex

Option 1. Use the Claude Code CLI

Copy the following command:

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

Paste the command in your terminal. Run the command.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp"
}

Open .claude.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp"
  }
}

Restart Claude Code.

For help configuring Claude Code, refer to the Claude Code documentation.By default, a single MCP server connection provides access to all clusters in the organization that you have permission to access. Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Option 1: Automatic installation

In the CockroachDB Cloud Console, select Integrations from the main navigation for your organization.
Click Connect MCP.
Select Cursor as the MCP Client.
Select Add to Cursor.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/mcp"
}

Open .cursor/mcp.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers.

"mcpServers": {
  "cockroachdb-cloud": {
    "url": "https://cockroachlabs.cloud/mcp"
  }
}

Restart Cursor.

For help configuring Cursor, refer to the Cursor documentation.By default, a single MCP server connection provides access to all clusters in the organization that you have permission to access. Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/mcp"
}

Open cline_mcp_settings.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "streamableHttp",
    "url": "https://cockroachlabs.cloud/mcp"
  }
}

Restart Cline.

For help configuring Cline, refer to the Cline documentation.By default, a single MCP server connection provides access to all clusters in the organization that you have permission to access. Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Option 1: Automatic installation

In the CockroachDB Cloud Console, select Integrations from the main navigation for your organization.
Click Connect MCP.
Select GitHub Copilot as the MCP Client.
Select Add to GitHub Copilot.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp"
}

Open .vscode/mcp.json.

Find "servers". Include the JSON snippet in the list of MCP servers.

"servers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp"
  }
}

Restart GitHub Copilot.

For help configuring GitHub Copilot, refer to the VS Code documentation.By default, a single MCP server connection provides access to all clusters in the organization that you have permission to access. Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Option 1. Use the Codex CLI

Copy the following command:

codex mcp add cockroachdb-cloud --url https://cockroachlabs.cloud/mcp

Paste the command in your terminal. Run the command.

Option 2: Manually modify TOML

Copy the following TOML snippet:

[mcp_servers.cockroachdb-cloud]
url = "https://cockroachlabs.cloud/mcp"

Open ~/.codex/config.toml.
Add the snippet to the file.
Restart Codex.

For help configuring Codex, refer to the Codex documentation.By default, a single MCP server connection provides access to all clusters in the organization that you have permission to access. Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Step 3. Update tool configuration

The MCP server URL: https://cockroachlabs.cloud/mcp
A header containing your Cluster ID: "mcp-cluster-id": "{your-cluster-id}"

Claude Code
Cursor
Cline
GitHub Copilot
Codex

Option 1. Use the Claude Code CLI

Copy the following command:

claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "mcp-cluster-id: {your-cluster-id}"

Paste the command in your terminal, replacing the placeholder with your Cluster ID. Run the command.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}"
  }
}

Open .claude.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}"
    }
  }
}

Restart Claude Code.

For help configuring Claude Code, refer to the Claude Code documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Automatic installation from the Cloud Console configures the connection at the organization scope. To scope the connection to a single cluster, modify the JSON manually:

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}"
  }
}

Open .cursor/mcp.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID.

"mcpServers": {
  "cockroachdb-cloud": {
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}"
    }
  }
}

Restart Cursor.

For help configuring Cursor, refer to the Cursor documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}"
  }
}

Open cline_mcp_settings.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "streamableHttp",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}"
    }
  }
}

Restart Cline.

For help configuring Cline, refer to the Cline documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Automatic installation from the Cloud Console configures the connection at the organization scope. To scope the connection to a single cluster, modify the JSON manually:

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}"
  }
}

Open .vscode/mcp.json.

Find "servers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID.

"servers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}"
    }
  }
}

Restart GitHub Copilot.

For help configuring GitHub Copilot, refer to the VS Code documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following TOML snippet:

[mcp_servers.cockroachdb-cloud]
url = "https://cockroachlabs.cloud/mcp"
http_headers = { "mcp-cluster-id" = "{your-cluster-id}" }

Open ~/.codex/config.toml.
Add the snippet to the file, replacing the placeholder with your Cluster ID.
Restart Codex.

For help configuring Codex, refer to the Codex documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Step 4. Connect and authenticate

After configuring the MCP server, access the MCP server connection settings using your tool’s interface and complete the authentication flow:

Claude Code
Cursor
Cline
GitHub Copilot
Codex

Run claude /mcp in your terminal.
Select the new server configuration cockroachdb-cloud and select Authenticate.
If you are not currently logged in to your CockroachDB Cloud account, you will be directed to the login page in your browser. Log in.
If you are a member of multiple CockroachDB Cloud , you will be directed to the Organization Selection modal in your browser. Select the organization whose clusters you want the MCP server connection to access.
You will be directed to the Authorize MCP Access modal in your browser. This modal will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Use the Cursor interface to access MCP server connection settings.
Select the new server configuration cockroachdb-cloud and select Authenticate.
If you are not currently logged in to your CockroachDB Cloud account, you will be directed to the login page in your browser. Log in.
If you are a member of multiple CockroachDB Cloud , you will be directed to the Organization Selection modal in your browser. Select the organization whose clusters you want the MCP server connection to access.
You will be directed to the Authorize MCP Access modal in your browser. This modal will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Use the Cline interface to access MCP server connection settings.
Select the new server configuration cockroachdb-cloud and select Authenticate.
If you are not currently logged in to your CockroachDB Cloud account, you will be directed to the login page in your browser. Log in.
If you are a member of multiple CockroachDB Cloud , you will be directed to the Organization Selection modal in your browser. Select the organization whose clusters you want the MCP server connection to access.
You will be directed to the Authorize MCP Access modal in your browser. This modal will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Use the GitHub Copilot interface to access MCP server connection settings.
Select the new server configuration cockroachdb-cloud and select Authenticate.
If you are not currently logged in to your CockroachDB Cloud account, you will be directed to the login page in your browser. Log in.
If you are a member of multiple CockroachDB Cloud , you will be directed to the Organization Selection modal in your browser. Select the organization whose clusters you want the MCP server connection to access.
You will be directed to the Authorize MCP Access modal in your browser. This modal will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Run codex mcp login cockroachdb-cloud in your terminal.
If you are not currently logged in to your CockroachDB Cloud account, you will be directed to the login page in your browser. Log in.
If you are a member of multiple CockroachDB Cloud , you will be directed to the Organization Selection modal in your browser. Select the organization whose clusters you want the MCP server connection to access.
You will be directed to the Authorize MCP Access modal in your browser. This modal will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Step 2. Choose your cluster scope

By default, an MCP server connection can access every cluster in the organization that the service account has permission to access. If you want to prevent your AI tool from switching between clusters, you can scope the connection to a single cluster. Single cluster configurations add an mcp-cluster-id header: when this header is set, all MCP tools will operate on that cluster, and tool calls that pass in a different cluster_id will fail with an error.If you choose to limit your connection to a single cluster, find your Cluster ID in the URL of the cluster’s : https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview.Select an option:

All clusters
Single cluster

Step 3. Update tool configuration

The MCP server URL: https://cockroachlabs.cloud/mcp
A header containing a bearer token: "Authorization: Bearer {your-service-account-api-key}". This should contain the secret key generated when creating your service account.

Claude Code
Cursor
Cline
GitHub Copilot
Codex

Option 1. Use the Claude Code CLI

Copy the following command:

claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "Authorization: Bearer {your-service-account-api-key}"

Paste the command in your terminal, replacing the placeholder. Run the command.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .claude.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Claude Code.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .cursor/mcp.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder.

"mcpServers": {
  "cockroachdb-cloud": {
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Cursor.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open cline_mcp_settings.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "streamableHttp",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Cline.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .vscode/mcp.json.

Find "servers". Include the JSON snippet in the list of MCP servers, replacing the placeholder.

"servers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart GitHub Copilot.

Copy the following TOML snippet:

[mcp_servers.cockroachdb-cloud]
url = "https://cockroachlabs.cloud/mcp"
http_headers = { "Authorization" = "Bearer {your-service-account-api-key}" }

Open ~/.codex/config.toml.
Add the snippet to the file, replacing the placeholder.
Restart Codex.

Step 3. Update tool configuration

The MCP server URL: https://cockroachlabs.cloud/mcp
A header containing your Cluster ID: "mcp-cluster-id": "{your-cluster-id}"
A header containing a bearer token: "Authorization: Bearer {your-service-account-api-key}". This should contain the secret key generated when creating your service account.

Claude Code
Cursor
Cline
GitHub Copilot
Codex

Option 1. Use the Claude Code CLI

Copy the following command:

claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "mcp-cluster-id: {your-cluster-id}" --header "Authorization: Bearer {your-service-account-api-key}"

Paste the command in your terminal, replacing the placeholder with your Cluster ID and the placeholder with your API key. Run the command.

Option 2: Manually modify JSON

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}",
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .claude.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID and the placeholder with your API key.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}",
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Claude Code.

For help configuring Claude Code, refer to the Claude Code documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}",
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .cursor/mcp.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID and the placeholder with your API key.

"mcpServers": {
  "cockroachdb-cloud": {
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}",
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Cursor.

For help configuring Cursor, refer to the Cursor documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}",
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open cline_mcp_settings.json.

Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID and the placeholder with your API key.

"mcpServers": {
  "cockroachdb-cloud": {
    "type": "streamableHttp",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}",
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart Cline.

For help configuring Cline, refer to the Cline documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp",
  "headers": {
    "mcp-cluster-id": "{your-cluster-id}",
    "Authorization": "Bearer {your-service-account-api-key}"
  }
}

Open .vscode/mcp.json.

Find "servers". Include the JSON snippet in the list of MCP servers, replacing the placeholder with your Cluster ID and the placeholder with your API key.

"servers": {
  "cockroachdb-cloud": {
    "type": "http",
    "url": "https://cockroachlabs.cloud/mcp",
    "headers": {
      "mcp-cluster-id": "{your-cluster-id}",
      "Authorization": "Bearer {your-service-account-api-key}"
    }
  }
}

Restart GitHub Copilot.

For help configuring GitHub Copilot, refer to the VS Code documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Copy the following TOML snippet:

[mcp_servers.cockroachdb-cloud]
url = "https://cockroachlabs.cloud/mcp"
http_headers = { "mcp-cluster-id" = "{your-cluster-id}", "Authorization" = "Bearer {your-service-account-api-key}" }

Open ~/.codex/config.toml.
Add the snippet to the file, replacing the placeholder with your Cluster ID and the placeholder with your API key.
Restart Codex.

For help configuring Codex, refer to the Codex documentation.Cockroach Labs recommends configuring one MCP server connection per tool, using one authentication method.

Step 4. Connect and authenticate

If the provided API key is active, there should be no further authorization steps. The MCP server connection’s access permissions are determined by the associated with this service account.

Use the MCP server

The CockroachDB Cloud MCP server provides several tools that enable you to read cluster data and metadata:

Tool	Description
`list_clusters`	List all accessible clusters.
`get_cluster`	Get detailed cluster information.
`list_databases`	List databases in the cluster.
`list_tables`	List tables in a database.
`get_table_schema`	Get detailed schema for a table.
`select_query`	Execute a statement.
`explain_query`	Execute an statement.
`show_statement`	Execute a statement.
`show_running_queries`	List currently executing queries.

There are also several tools that enable you to write cluster data:

Tool	Description
`create_database`	Create a new database.
`create_table`	Create a new table.
`insert_rows`	Insert rows into a table.

MCP tools can read from and write to any cluster in the organization that your user or service account has permission to access. Use the list_clusters tool to see the clusters that are available to the connection. If you have scoped the connection to a single cluster (Step 2), all tools operate only on that cluster. Use natural language prompts to read from and write to the cluster. These prompts do not need to reference the names of the tools. Prompts can be simple, for example:

List all of the tables in the movr database.

They can also be complex and conversational, for example:

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.

Limits

To keep results within your AI tool’s context window and protect cluster resources, the MCP server enforces the following limits on tool calls:

Each tool call executes exactly one SQL statement, with a maximum length of 16,384 characters.
Each query times out after 20 seconds.
Each response is limited to 10 KiB.
If a SELECT statement passed to select_query does not specify a LIMIT, a LIMIT of 25 rows is applied. An explicit LIMIT can be at most 10,000 rows (LIMIT ALL is not allowed); use LIMIT with OFFSET to paginate through larger result sets.
list_databases and list_tables return 100 results by default, and at most 10,000.
show_statement returns at most 100 rows, and supports only SHOW statements that introspect schemas and cluster configuration, such as SHOW SCHEMAS, SHOW INDEXES, SHOW CONSTRAINTS, and SHOW REGIONS.
explain_query can explain only SELECT, INSERT, and CREATE TABLE statements. EXPLAIN ANALYZE is not supported, as it would execute the statement.
Tools cannot access the system, crdb_internal, pg_catalog, information_schema, and pg_extension schemas.

Allowlist redirect URLs for custom MCP clients

When an MCP client connects using OAuth, the authentication flow ends by redirecting your browser to a redirect URL specified by the client. This is where the client receives the authorization code that it exchanges for an access token. CockroachDB Cloud only redirects to URLs that have been allowlisted for your organization. An allowlisted redirect URL permits any port and any path on the allowed host. The hostnames used by the AI tools that are documented on this page, along with redirect URLs that resolve to the local machine, are allowlisted by default. If you connect a custom or enterprise MCP client, you may need to manually add the client’s redirect URL to the allowlist before OAuth authentication can complete. Your ability to manage the allowlist depends on your :

Role	Access
	Full read/write: create, view, and manage redirect URLs and OAuth apps.
	Read-only: view allowlisted redirect URLs, but cannot create or modify them.

To allowlist a redirect URL, an Organization Admin can:

Go to Governance > OAuth apps in the CockroachDB Cloud Console.
Click Add redirect URL.
In the modal that appears, enter the redirect URL used by the MCP client, then click Add.

Monitoring and Alerting

Tools

Upgrade

Disaster Recovery

Connect to the CockroachDB Cloud MCP Server

Before you begin

Connect to the MCP server

Step 1. Choose your authentication method

Step 2. Choose your cluster scope

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Option 1: Automatic installation

Option 2: Manually modify JSON

Option 1: Automatic installation

Option 2: Manually modify JSON

Option 1. Use the Codex CLI

Option 2: Manually modify TOML

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 4. Connect and authenticate

Step 2. Choose your cluster scope

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 4. Connect and authenticate

Use the MCP server

Limits

Allowlist redirect URLs for custom MCP clients

See also

​Before you begin

​Connect to the MCP server

​Step 1. Choose your authentication method

​Step 2. Choose your cluster scope

​Step 3. Update tool configuration

​Option 1. Use the Claude Code CLI

​Option 2: Manually modify JSON

​Option 1: Automatic installation

​Option 2: Manually modify JSON

​Option 1: Automatic installation

​Option 2: Manually modify JSON

​Option 1. Use the Codex CLI

​Option 2: Manually modify TOML

​Step 3. Update tool configuration

​Option 1. Use the Claude Code CLI

​Option 2: Manually modify JSON

​Step 4. Connect and authenticate

​Step 2. Choose your cluster scope

​Step 3. Update tool configuration

​Option 1. Use the Claude Code CLI

​Option 2: Manually modify JSON

​Step 3. Update tool configuration

​Option 1. Use the Claude Code CLI

​Option 2: Manually modify JSON

​Step 4. Connect and authenticate

​Use the MCP server

​Limits

​Allowlist redirect URLs for custom MCP clients

​See also

Before you begin

Connect to the MCP server

Step 1. Choose your authentication method

Step 2. Choose your cluster scope

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Option 1: Automatic installation

Option 2: Manually modify JSON

Option 1: Automatic installation

Option 2: Manually modify JSON

Option 1. Use the Codex CLI

Option 2: Manually modify TOML

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 4. Connect and authenticate

Step 2. Choose your cluster scope

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 3. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

Step 4. Connect and authenticate

Use the MCP server

Limits

Allowlist redirect URLs for custom MCP clients

See also