Connect to the CockroachDB Cloud MCP Server

On this page

CockroachDB Cloud includes a managed Model Context Protocol (MCP) server that enables AI coding tools and AI agents to access a cluster. 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 SELECT statements, and inserting rows into a table.

This page explains how to connect AI tools to the CockroachDB Cloud MCP server, including detailed instructions for the following tools:

Claude Code
Cursor
Cline
Github Copilot

Before you begin

Create a CockroachDB cluster.
- Note the Cluster ID in the URL of the Cluster Overview Page: 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 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.
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.
- Copy the secret key that's generated upon service account creation.

Connect to the MCP Server

Warning:

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

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

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.

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 {your-cluster-id} placeholder. 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 {your-cluster-id} placeholder.

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

Restart Claude Code.

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 {your-cluster-id} and {your-service-account-api-key} placeholders. 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 {your-cluster-id} and {your-service-account-api-key} 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}"
    }
  }
}

Restart Claude Code.

For help configuring Claude Code, refer to the Claude Code documentation.

Option 1: Automatic installation

Navigate to the Cluster Overview Page for the cluster that you want to manage with the MCP server connection.
Select Connect, then the Model Context Protocol (MCP) tab.
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",
  "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 {your-cluster-id} placeholder.

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

Restart Cursor.

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 {your-cluster-id} and {your-service-account-api-key} placeholders.

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

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 {your-cluster-id} placeholder.

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

Restart Cline.

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 {your-cluster-id} and {your-service-account-api-key} 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}"
    }
  }
}

Restart Cline.

For help configuring Cline, refer to the Cline documentation.

Option 1: Automatic installation

Navigate to the Cluster Overview Page for the cluster that you want to manage with the MCP server connection.
Select Connect, then the Model Context Protocol (MCP) tab.
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",
  "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 {your-cluster-id} placeholder.

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

Restart GitHub Copilot.

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 {your-cluster-id} and {your-service-account-api-key} 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}"
    }
  }
}

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, run the following command in your terminal:
```
claude /mcp
```
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 organizations, you wil 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.
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.

After configuring the MCP server, 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 organizations, you wil 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.
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.

After configuring the MCP server, 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 organizations, you wil 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.
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.

After configuring the MCP server, 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 organizations, you wil 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.
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.

If the provided API key is active, there should be no futher 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_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.

Pricing

Contact us

Sign In

Connect to the CockroachDB Cloud MCP Server

Before you begin

Connect to the MCP Server

Step 1. Choose your authentication method

Step 2. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

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

Step 3. Connect and authenticate

Use the MCP server

See also

Tell us about your experience

Thank you for your feedback!

Explore More Documentation:

Connect to the CockroachDB Cloud MCP Server

Before you begin

Connect to the MCP Server

Step 1. Choose your authentication method

Step 2. Update tool configuration

Option 1. Use the Claude Code CLI

Option 2: Manually modify JSON

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

Step 3. Connect and authenticate

Use the MCP server

See also

Tell us about your experience

Select the problem area

Thank you for your feedback!

Explore More Documentation: