> ## 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. # Connect to the CockroachDB Cloud 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} ; }; CockroachDB Cloud includes a managed [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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 `SELECT` 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](#allowlist-redirect-urls-for-custom-mcp-clients). 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 * Create a CockroachDB cluster. * If you plan to connect to the MCP server using OAuth, ensure that the user managing the MCP server connection is able to log in to the Cloud Console. Ensure that the user has been assigned the Cluster Admin role or the Cluster Operator 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](#allowlist-redirect-urls-for-custom-mcp-clients) by an Organization Admin. * If you plan to connect to the MCP server using an API key, create a service account and an API key in the CockroachDB Cloud Console. Ensure that the service account has been assigned the Cluster Admin role or the Cluster Operator 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: ### 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 Overview page: `https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview`. Select an option: ### 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. #### Option 1. Use the Claude Code CLI 1. Copy the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http ``` 2. Paste the command in your terminal. Run the command. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp" } ``` 2. Open `.claude.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp" } } ``` 4. 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 1. In the CockroachDB Cloud Console, select **Integrations** from the main navigation for your organization. 2. Click **Connect MCP**. 3. Select **Cursor** as the MCP Client. 4. Select **Add to Cursor**. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp" } ``` 2. Open `.cursor/mcp.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp" } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp" } ``` 2. Open `cline_mcp_settings.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp" } } ``` 4. 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 1. In the CockroachDB Cloud Console, select **Integrations** from the main navigation for your organization. 2. Click **Connect MCP**. 3. Select **GitHub Copilot** as the MCP Client. 4. Select **Add to GitHub Copilot**. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp" } ``` 2. Open `.vscode/mcp.json`. 3. Find `"servers"`. Include the JSON snippet in the list of MCP servers. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "servers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp" } } ``` 4. 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 1. Copy the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} codex mcp add cockroachdb-cloud --url https://cockroachlabs.cloud/mcp ``` 2. Paste the command in your terminal. Run the command. #### Option 2: Manually modify TOML 1. Copy the following TOML snippet: ```toml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} [mcp_servers.cockroachdb-cloud] url = "https://cockroachlabs.cloud/mcp" ``` 2. Open `~/.codex/config.toml`. 3. Add the snippet to the file. 4. 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 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` * A header containing your Cluster ID: `"mcp-cluster-id": "{your-cluster-id}"` 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. #### Option 1. Use the Claude Code CLI 1. Copy the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "mcp-cluster-id: {your-cluster-id}" ``` 2. Paste the command in your terminal, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. Run the command. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } ``` 2. Open `.claude.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } } ``` 4. 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: 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } ``` 2. Open `.cursor/mcp.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } ``` 2. Open `cline_mcp_settings.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } } ``` 4. 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: 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } ``` 2. Open `.vscode/mcp.json`. 3. Find `"servers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "servers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}" } } } ``` 4. 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. 1. Copy the following TOML snippet: ```toml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} [mcp_servers.cockroachdb-cloud] url = "https://cockroachlabs.cloud/mcp" http_headers = { "mcp-cluster-id" = "{your-cluster-id}" } ``` 2. Open `~/.codex/config.toml`. 3. Add the snippet to the file, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID. 4. 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: 1. Run `claude /mcp` in your terminal. 2. Select the new server configuration `cockroachdb-cloud` and select **Authenticate**. 3. 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. 4. If you are a member of multiple CockroachDB Cloud organizations, 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. 5. 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**. 1. Use the Cursor interface to access MCP server connection settings. 2. Select the new server configuration `cockroachdb-cloud` and select **Authenticate**. 3. 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. 4. If you are a member of multiple CockroachDB Cloud organizations, 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. 5. 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**. 1. Use the Cline interface to access MCP server connection settings. 2. Select the new server configuration `cockroachdb-cloud` and select **Authenticate**. 3. 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. 4. If you are a member of multiple CockroachDB Cloud organizations, 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. 5. 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**. 1. Use the GitHub Copilot interface to access MCP server connection settings. 2. Select the new server configuration `cockroachdb-cloud` and select **Authenticate**. 3. 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. 4. If you are a member of multiple CockroachDB Cloud organizations, 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. 5. 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**. 1. Run `codex mcp login cockroachdb-cloud` in your terminal. 2. 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. 3. If you are a member of multiple CockroachDB Cloud organizations, 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. 4. 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 Overview page: `https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview`. Select an option: ### 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` * 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. 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. #### Option 1. Use the Claude Code CLI 1. Copy the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "Authorization: Bearer {your-service-account-api-key}" ``` 2. Paste the command in your terminal, replacing the {'{your-service-account-api-key}'} placeholder. Run the command. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.claude.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-service-account-api-key}'} placeholder. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.cursor/mcp.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-service-account-api-key}'} placeholder. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `cline_mcp_settings.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-service-account-api-key}'} placeholder. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.vscode/mcp.json`. 3. Find `"servers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-service-account-api-key}'} placeholder. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "servers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following TOML snippet: ```toml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} [mcp_servers.cockroachdb-cloud] url = "https://cockroachlabs.cloud/mcp" http_headers = { "Authorization" = "Bearer {your-service-account-api-key}" } ``` 2. Open `~/.codex/config.toml`. 3. Add the snippet to the file, replacing the {'{your-service-account-api-key}'} placeholder. 4. 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 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` * 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. 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. #### Option 1. Use the Claude Code CLI 1. Copy the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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}" ``` 2. Paste the command in your terminal, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. Run the command. #### Option 2: Manually modify JSON 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.claude.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.cursor/mcp.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `cline_mcp_settings.json`. 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "mcpServers": { "cockroachdb-cloud": { "type": "streamableHttp", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following JSON snippet: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } ``` 2. Open `.vscode/mcp.json`. 3. Find `"servers"`. Include the JSON snippet in the list of MCP servers, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "servers": { "cockroachdb-cloud": { "type": "http", "url": "https://cockroachlabs.cloud/mcp", "headers": { "mcp-cluster-id": "{your-cluster-id}", "Authorization": "Bearer {your-service-account-api-key}" } } } ``` 4. 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. 1. Copy the following TOML snippet: ```toml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} [mcp_servers.cockroachdb-cloud] url = "https://cockroachlabs.cloud/mcp" http_headers = { "mcp-cluster-id" = "{your-cluster-id}", "Authorization" = "Bearer {your-service-account-api-key}" } ``` 2. Open `~/.codex/config.toml`. 3. Add the snippet to the file, replacing the {'{your-cluster-id}'} placeholder with your Cluster ID and the {'{your-service-account-api-key}'} placeholder with your API key. 4. 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 role(s) 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 `SELECT` statement. | | `explain_query` | Execute an `EXPLAIN` statement. | | `show_statement` | Execute a `SHOW` 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](#step-2-choose-your-cluster-scope)), 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: ```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 service appointments table to the movr database. I need to track when customers schedule service appointments for their vehicles. For the schema, I'm thinking we need: - Appointment ID (primary key) - Customer reference (foreign key to movr.customers) - Vehicle reference (foreign key to movr.vehicles) - Appointment date/time - Service type (oil change, inspection, repair, etc.) - Status (scheduled, completed, cancelled, no-show) - Assigned technician (foreign key to movr.technicians) - Estimated cost - Notes Let's include a secondary index on the status 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 organization role: | Role | Access | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Organization Admin | Full read/write: create, view, and manage redirect URLs and OAuth apps. | | Organization Member | Read-only: view allowlisted redirect URLs, but cannot create or modify them. | To allowlist a redirect URL, an Organization Admin can: 1. Go to **Governance** > **OAuth apps** in the CockroachDB Cloud Console. 2. Click **Add redirect URL**. 3. In the modal that appears, enter the redirect URL used by the MCP client, then click **Add**. ## See also * Agent Skills for CockroachDB * Docs MCP Server * Schema Design Overview * Managing Access * Authorization * `SELECT` * `EXPLAIN`