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 a cluster. Your AI tools can explore live schemas and run queries against a cluster using OAuth or API key authentication. A user can interact with their cluster using natural language prompts to perform read and write operations such as listing tables, executing statements, and inserting rows into a table.

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

Before you begin

• .
  • Note the Cluster ID in the URL of the : https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview.
• 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 role or the role.
• 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 role or the role.
  • Copy the secret key that’s generated upon service account creation.

Connect to the MCP Server

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

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.

Step 1. Choose your authentication method

OAuth

Step 2. 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
• 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.

Claude Code

Option 1. Use the Claude Code CLI

1. Copy the following command:

   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 placeholder. Run the command.

Option 2: Manually modify JSON

1. Copy the following JSON snippet:

   "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 placeholder.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Cursor

Option 1: Automatic installation

1. Navigate to the for the cluster that you want to manage with the MCP server connection.
2. Select Connect, then the Model Context Protocol (MCP) tab.
3. Select Cursor as the MCP Client.
4. Select Add to Cursor.

Option 2: Manually modify JSON

1. Copy the following JSON snippet:

   "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 placeholder.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Cline

1. Copy the following JSON snippet:

   "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 placeholder.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Github Copilot

Option 1: Automatic installation

1. Navigate to the for the cluster that you want to manage with the MCP server connection.
2. Select Connect, then the Model Context Protocol (MCP) tab.
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:

   "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 placeholder.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Step 3. Connect and authenticate

After configuring the MCP server, access the MCP server connection settings using your tool’s interface. The exact method varies by tool:

• Claude Code: Run claude /mcp in your terminal
• Cursor: Use the Cursor interface to access MCP server connection settings
• Cline: Use the Cline interface to access MCP server connection settings
• GitHub Copilot: Use the GitHub Copilot interface to access MCP server connection settings

Then complete the authentication flow:

1. Select the new server configuration cockroachdb-cloud and select Authenticate.
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 , you will be directed to the Organization Selection modal in your browser. Select the organization associated with the cluster that you have included in the tool configuration.
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.

API Key

Step 2. 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
• 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.

Claude Code

Option 1. Use the Claude Code CLI

1. 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}"
   

2. Paste the command in your terminal, replacing the and placeholders. Run the command.

Option 2: Manually modify JSON

1. 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}"
     }
   }
   

2. Open .claude.json.

3. Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the and placeholders.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Cursor

1. 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}"
     }
   }
   

2. Open .cursor/mcp.json.

3. Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the and placeholders.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Cline

1. 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}"
     }
   }
   

2. Open cline_mcp_settings.json.

3. Find "mcpServers". Include the JSON snippet in the list of MCP servers, replacing the and placeholders.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Github Copilot

1. 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}"
     }
   }
   

2. Open .vscode/mcp.json.

3. Find "servers". Include the JSON snippet in the list of MCP servers, replacing the and placeholders.

   "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.

While it’s possible to use multiple MCP server connections to connect your tool to multiple clusters at once, or to connect to the same cluster using different authentication methods, Cockroach Labs recommends connecting to one cluster using one authentication method.

Step 3. 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\_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.

The tool will only read or write to the cluster specified by the configuration that you updated in Step 2.

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 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.

See also