> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/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 <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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 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 <InternalLink version="stable" path="select-clause">`SELECT`</InternalLink> 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

* <InternalLink path="create-a-basic-cluster">Create a CockroachDB cluster</InternalLink>.
  * Note the Cluster ID in the URL of the <InternalLink version="cockroachcloud" path="overview-page">Overview page</InternalLink>: `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 <InternalLink path="authentication">is able to log in</InternalLink> to the Cloud Console. Ensure that the user has been assigned the <InternalLink path="authorization#cluster-admin">Cluster Admin</InternalLink> role or the <InternalLink path="authorization#cluster-operator">Cluster Operator</InternalLink> role.
* If you plan to connect to the MCP server using an API key, create a <InternalLink path="managing-access#manage-service-accounts">service account</InternalLink> and an <InternalLink path="managing-access#api-access">API key</InternalLink> in the CockroachDB Cloud Console. Ensure that the service account has been assigned the <InternalLink path="authorization#cluster-admin">Cluster Admin</InternalLink> role or the <InternalLink path="authorization#cluster-operator">Cluster Operator</InternalLink> role.
  * Copy the secret key that's generated upon service account creation.

## Connect to the MCP Server

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

### Step 1. Choose your authentication method

<Tabs>
  <Tab title="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.

    <AccordionGroup>
      <Accordion title="Claude Code">
        #### 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 <code>{'{your-cluster-id}'}</code> 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": {
               "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 <code>{'{your-cluster-id}'}</code> placeholder.

           ```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 <a href="https://code.claude.com/docs/en/mcp">Claude Code documentation</a>.

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

      <Accordion title="Cursor">
        #### Option 1: Automatic installation

        1. Navigate to the <InternalLink version="cockroachcloud" path="overview-page">Overview page</InternalLink> 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:

           ```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 <code>{'{your-cluster-id}'}</code> placeholder.

           ```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 <a href="https://cursor.com/docs/context/mcp#installing-mcp-servers">Cursor documentation</a>.

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

      <Accordion title="Cline">
        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 <code>{'{your-cluster-id}'}</code> placeholder.

           ```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 <a href="https://docs.cline.bot/mcp/adding-and-configuring-servers">Cline documentation</a>.

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

      <Accordion title="Github Copilot">
        #### Option 1: Automatic installation

        1. Navigate to the <InternalLink version="cockroachcloud" path="overview-page">Overview page</InternalLink> 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:

           ```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 <code>{'{your-cluster-id}'}</code> placeholder.

           ```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 <a href="https://code.visualstudio.com/docs/copilot/customization/mcp-servers">VS Code documentation</a>.

        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.
      </Accordion>
    </AccordionGroup>

    ### 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 <InternalLink path="authorization">organizations</InternalLink>, 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**.
  </Tab>

  <Tab title="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.

    <AccordionGroup>
      <Accordion title="Claude Code">
        #### 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 <code>{'{your-cluster-id}'}</code> and <code>{'{your-service-account-api-key}'}</code> placeholders. 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 <code>{'{your-cluster-id}'}</code> and <code>{'{your-service-account-api-key}'}</code> placeholders.

           ```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 <a href="https://code.claude.com/docs/en/mcp">Claude Code documentation</a>.

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

      <Accordion title="Cursor">
        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 <code>{'{your-cluster-id}'}</code> and <code>{'{your-service-account-api-key}'}</code> placeholders.

           ```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 <a href="https://cursor.com/docs/context/mcp#installing-mcp-servers">Cursor documentation</a>.

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

      <Accordion title="Cline">
        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 <code>{'{your-cluster-id}'}</code> and <code>{'{your-service-account-api-key}'}</code> placeholders.

           ```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 <a href="https://docs.cline.bot/mcp/adding-and-configuring-servers">Cline documentation</a>.

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

      <Accordion title="Github Copilot">
        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 <code>{'{your-cluster-id}'}</code> and <code>{'{your-service-account-api-key}'}</code> placeholders.

           ```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 <a href="https://code.visualstudio.com/docs/copilot/customization/mcp-servers">VS Code documentation</a>.

        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.
      </Accordion>
    </AccordionGroup>

    ### 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 <InternalLink path="authorization#organization-user-roles">role(s)</InternalLink> associated with this service account.
  </Tab>
</Tabs>

## 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 <InternalLink version="stable" path="select-clause">`SELECT`</InternalLink> statement. |
| `explain\_query`         | Execute an <InternalLink version="stable" path="explain">`EXPLAIN`</InternalLink> 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:

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

## See also

* <InternalLink version="stable" path="agent-skills">Agent Skills for CockroachDB</InternalLink>
* <InternalLink version="stable" path="docs-mcp-integration">Docs MCP Server</InternalLink>
* <InternalLink version="stable" path="schema-design-overview">Schema Design Overview</InternalLink>
* <InternalLink path="managing-access">Managing Access</InternalLink>
* <InternalLink path="authorization">Authorization</InternalLink>
* <InternalLink version="stable" path="select-clause">`SELECT`</InternalLink>
* <InternalLink version="stable" path="explain">`EXPLAIN`</InternalLink>