From 4ab96df6e74e800bb6bedcb9d38144c2ad63620f Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Wed, 25 Feb 2026 11:32:24 -0500 Subject: [PATCH 1/3] Cloud MCP server getting started guide --- .../v26.1/sidebar-data/cloud-deployments.json | 14 +++++-- .../mcp-server-getting-started.md | 40 +++++++++++++++++++ 2 files changed, 50 insertions(+), 4 deletions(-) create mode 100644 src/current/cockroachcloud/mcp-server-getting-started.md diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 88a04d9d0c2..e988b2219e4 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -610,15 +610,21 @@ ] }, { - "title": "CockroachDB Cloud API", + "title": "ccloud CLI", "urls": [ - "/cockroachcloud/cloud-api.html" + "/cockroachcloud/ccloud-get-started.html" ] }, { - "title": "ccloud CLI", + "title": "MCP Server", "urls": [ - "/cockroachcloud/ccloud-get-started.html" + "/cockroachcloud/mcp-server-get-started.html" + ] + }, + { + "title": "CockroachDB Cloud API", + "urls": [ + "/cockroachcloud/cloud-api.html" ] } ] diff --git a/src/current/cockroachcloud/mcp-server-getting-started.md b/src/current/cockroachcloud/mcp-server-getting-started.md new file mode 100644 index 00000000000..65fbcc3a3c5 --- /dev/null +++ b/src/current/cockroachcloud/mcp-server-getting-started.md @@ -0,0 +1,40 @@ +--- +title: Connect to the CockroachDB Cloud MCP Server +summary: Description of the MCP Server, what it does, and a step-by-step guide on how to set it up. +toc: true +--- + +CockroachDB Cloud includes a managed MCP server that enables AI coding tools such as Claude, VS 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. + +[More about what this server enables] + +This page explains how to connect your AI tools to the CockroachDB Cloud MCP server. + +## Before you begin + +- Create a [service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and [API key]({% link cockroachcloud/managing-access.md %}#api-access) in the [CockroachDB Cloud Console](https://cockroachlabs.cloud). + +## Step 1. Update tool configuration + +Different AI tools might have slightly different ways of connecting to an MCP server via HTTP. Review the documentation for the tool to understand how to configure it. This will normally involve adding a JSON snippet to a configuration file, which will look something like this: + +~~~json +"cockroachdb-cloud": { + "type": "http", + "url": "https://management-staging.crdb.io/mcp", + "headers": { + "Authorization": "Bearer {service-account-api-key}" + } +} +~~~ + +Replace the `{service-account-api-key}` placeholder with the API key generated for your CockroachDB Cloud service account. + +Though the specific JSON snippet might look slightly different for each tool, the + + +## Step 2. Authenticate and connect + +## Step 3. Use the MCP server + +## See also \ No newline at end of file From 546bd17d9680aae0d0cc5b45b9a774871ea1ef5d Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Wed, 25 Feb 2026 14:42:00 -0500 Subject: [PATCH 2/3] added more detail --- .../cockroachcloud/mcp-server-getting-started.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/current/cockroachcloud/mcp-server-getting-started.md b/src/current/cockroachcloud/mcp-server-getting-started.md index 65fbcc3a3c5..929f279f5fc 100644 --- a/src/current/cockroachcloud/mcp-server-getting-started.md +++ b/src/current/cockroachcloud/mcp-server-getting-started.md @@ -4,7 +4,7 @@ summary: Description of the MCP Server, what it does, and a step-by-step guide o toc: true --- -CockroachDB Cloud includes a managed MCP server that enables AI coding tools such as Claude, VS 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. +CockroachDB Cloud includes a managed Model Context Protocol (MCP) server that enables AI coding tools such as Claude, VS 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. [More about what this server enables] @@ -12,11 +12,13 @@ This page explains how to connect your AI tools to the CockroachDB Cloud MCP ser ## Before you begin -- Create a [service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and [API key]({% link cockroachcloud/managing-access.md %}#api-access) in the [CockroachDB Cloud Console](https://cockroachlabs.cloud). +- Create a [service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and [API key]({% link cockroachcloud/managing-access.md %}#api-access) in the CockroachDB Cloud Console. Ensure that the service account has been [assigned roles]({% link cockroachcloud/authorization.md %}#organization-user-roles) that will enable your AI tools to perform desired actions. ## Step 1. Update tool configuration -Different AI tools might have slightly different ways of connecting to an MCP server via HTTP. Review the documentation for the tool to understand how to configure it. This will normally involve adding a JSON snippet to a configuration file, which will look something like this: +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 look something like this: ~~~json "cockroachdb-cloud": { @@ -30,11 +32,15 @@ Different AI tools might have slightly different ways of connecting to an MCP se Replace the `{service-account-api-key}` placeholder with the API key generated for your CockroachDB Cloud service account. -Though the specific JSON snippet might look slightly different for each tool, the +The specific JSON snippet might look slightly different for each tool, and the tool might offer CLI commands to simplify the configuration process. Review the documentation for the tool to understand how to configure it. ## Step 2. Authenticate and connect +{{site.data.alerts.callout_danger}} +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. +{{site.data.alerts.end}} + ## Step 3. Use the MCP server ## See also \ No newline at end of file From 429673b77149f7c2f6ca7789dda36f07dc644379 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Fri, 27 Feb 2026 12:42:34 -0500 Subject: [PATCH 3/3] finished first draft --- .../v26.1/sidebar-data/cloud-deployments.json | 2 +- .../mcp-server-getting-started.md | 288 ++++++++++++++++-- 2 files changed, 267 insertions(+), 23 deletions(-) diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index e988b2219e4..dbfd5bfecef 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -618,7 +618,7 @@ { "title": "MCP Server", "urls": [ - "/cockroachcloud/mcp-server-get-started.html" + "/cockroachcloud/mcp-server-getting-started.html" ] }, { diff --git a/src/current/cockroachcloud/mcp-server-getting-started.md b/src/current/cockroachcloud/mcp-server-getting-started.md index 929f279f5fc..e72cd56bfd9 100644 --- a/src/current/cockroachcloud/mcp-server-getting-started.md +++ b/src/current/cockroachcloud/mcp-server-getting-started.md @@ -4,43 +4,287 @@ summary: Description of the MCP Server, what it does, and a step-by-step guide o toc: true --- -CockroachDB Cloud includes a managed Model Context Protocol (MCP) server that enables AI coding tools such as Claude, VS 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. - -[More about what this server enables] +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. +{{site.data.alerts.callout_danger}} +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. +{{site.data.alerts.end}} + ## Before you begin -- Create a [service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and [API key]({% link cockroachcloud/managing-access.md %}#api-access) in the CockroachDB Cloud Console. Ensure that the service account has been [assigned roles]({% link cockroachcloud/authorization.md %}#organization-user-roles) that will enable your AI tools to perform desired actions. +- [Create a CockroachDB cluster]({% link cockroachcloud/create-a-basic-cluster.md %}). + - Note the Cluster ID in the URL of the [Cluster Overview Page]({% link cockroachcloud/cluster-overview-page.md %}): `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]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and an [API key]({% link cockroachcloud/managing-access.md %}#api-access) in the CockroachDB Cloud Console. Ensure that the service account has been assigned the [Cluster Admin]({% link cockroachcloud/authorization.md %}#cluster-admin) role or the [Cluster Operator]({% link cockroachcloud/authorization.md %}#cluster-operator) role. -## Step 1. Update tool configuration +## 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 look something like this: +
+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}`. +
-~~~json -"cockroachdb-cloud": { - "type": "http", - "url": "https://management-staging.crdb.io/mcp", - "headers": { - "Authorization": "Bearer {service-account-api-key}" - } -} -~~~ +
+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: -Replace the `{service-account-api-key}` placeholder with the API key generated for your CockroachDB Cloud service account. +- 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. Review the documentation for the tool to understand how to configure it. +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. -## Step 2. Authenticate and connect +
+ + + + +
-{{site.data.alerts.callout_danger}} -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. -{{site.data.alerts.end}} +
+
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "type": "http", + "url": "https://cockroachlabs.cloud/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. + +4. Restart Claude Code. + +5. 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**. +
+ +
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "type": "http", + "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}", + "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-cluster-id}` and `{your-service-account-api-key}` placeholders. + +4. 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)]({% link cockroachcloud/authorization.md %}#organization-user-roles) associated with this service account. +
+
+ +
+
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "url": "https://cockroachlabs.cloud/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. + +4. Restart Cursor. + +5. 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**. +
+ +
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}", + "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-cluster-id}` and `{your-service-account-api-key}` placeholders. + +4. 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)]({% link cockroachcloud/authorization.md %}#organization-user-roles) associated with this service account. +
+
+ +
+
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "type": "streamableHttp", + "url": "https://cockroachlabs.cloud/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. + +4. Restart Cline. + +5. 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**. +
+ +
+1. Copy the following JSON snippet: + + ~~~json + "cockroachdb-cloud": { + "type": "streamableHttp", + "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}", + "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-cluster-id}` and `{your-service-account-api-key}` placeholders. + +4. 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)]({% link cockroachcloud/authorization.md %}#organization-user-roles) associated with this service account. +
+
+ +
+
+1. Copy the following JSON snippet: + + ~~~json + "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. + +4. Restart GitHub Copilot. + +5. 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**. +
+ +
+1. Copy the following JSON snippet: + + ~~~json + "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}` and `{your-service-account-api-key}` placeholders. + +4. 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)]({% link cockroachcloud/authorization.md %}#organization-user-roles) 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 -## See also \ No newline at end of file +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`]({% link {{site.current_cloud_version}}/select-clause.md %}) statement. | +| `explain_query` | Execute an [`EXPLAIN`]({% link {{site.current_cloud_version}}/explain.md %}) 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](#step-2-update-tool-configuration). + +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 + +- [Schema Design Overview]({% link {{site.current_cloud_version}}/schema-design-overview.md %}) +- [Managing Access]({% link cockroachcloud/managing-access.md %}) +- [Authorization]({% link cockroachcloud/authorization.md %}) +- [`SELECT`]({% link {{site.current_cloud_version}}/select-clause.md %}) +- [`CREATE DATABASE`]({% link {{site.current_cloud_version}}/create-database.md %}) +- [`CREATE TABLE`]({% link {{site.current_cloud_version}}/create-table.md %}) +- [`EXPLAIN`]({% link {{site.current_cloud_version}}/explain.md %}) \ No newline at end of file