Docs Menu

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 such as Claude Code, Cursor, and AI agents to access a cluster. They can securely explore live schemas and run queries against a single selected cluster using OAuth or API key authentication. Users can interact with their cluster using natural language prompts to perform read operations (such as listing databases, querying tables, and exploring schemas) and write operations (such as creating databases and tables, and inserting rows into a table).

This page explains how to connect your AI tools to the CockroachDB Cloud MCP server.

Warning:

Use caution when granting cluster read/write access to an AI tool or agent, especially on a production cluster. Review your organization's security policies before doing so.

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

Step 1. Choose your authentication method

Step 2. Update tool configuration

Cockroach Labs enables access to its CockroachDB Cloud MCP server via HTTP.

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?cluster_id={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?cluster_id={your-cluster-id}
A header containing a bearer token: "Authorization: Bearer {your-service-account-api-key}".

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.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/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.
Restart Claude Code.
The first time you use Claude Code to connect to the MCP server, it will redirect you to OAuth verification. You will then be led to an Authorize MCP Access modal, which will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "http",
  "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}",
  "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 {your-cluster-id} and {your-service-account-api-key} placeholders.
Restart Claude Code.

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.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/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.
Restart Cursor.
The first time you use Cursor to connect to the MCP server, it will redirect you to OAuth verification. You will then be led to an Authorize MCP Access modal, which will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}",
  "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 {your-cluster-id} and {your-service-account-api-key} placeholders.
Restart Cursor.

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.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/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.
Restart Cline.
The first time you use Cline to connect to the MCP server, it will redirect you to OAuth verification. You will then be led to an Authorize MCP Access modal, which will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

Copy the following JSON snippet:

"cockroachdb-cloud": {
  "type": "streamableHttp",
  "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}",
  "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 {your-cluster-id} and {your-service-account-api-key} placeholders.
Restart Cline.

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.

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.
Restart GitHub Copilot.
The first time you use GitHub CoPilot to connect to the MCP server, it will redirect you to OAuth verification. You will then be led to an Authorize MCP Access modal, which will ask you to grant read and/or write permissions to this MCP server connection. Select one or both options, then click Authorize.

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.
Restart GitHub Copilot.

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.

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 just one single cluster using one authentication method.

Step 3. 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.
`execute_read_sql`	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.

See also

On this page

×

★ ★ ★ ★ ★

Please select a star rating above.

Tell us about your experience

Drop image here or click to browse

Please attach a screenshot of the area where you encountered the problem.

Thank you for your feedback!

Your input helps us improve our documentation.

Explore More Documentation: