> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the CockroachDB Cloud MCP server

The CockroachDB Cloud MCP connector routes your AI agent's tool calls to CockroachDB Cloud's own MCP server through Scalekit. Each user signs in to CockroachDB Cloud once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 12 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** Databases
**Tools:** 12: 9 read, 2 write, 1 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own CockroachDB Cloud MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=COCKROACHDBMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the CockroachDB Cloud MCP connection

   In **AgentKit > Connections**, create a CockroachDB Cloud MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   CockroachDB Cloud MCP server connections use your own OAuth app. Register one with CockroachDB Cloud MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the CockroachDB Cloud MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'cockroachdbmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize CockroachDB Cloud MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'cockroachdbmcp_get_cluster',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "cockroachdbmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize CockroachDB Cloud MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="cockroachdbmcp_get_cluster",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'cockroachdbmcp_explain_query',
  toolInput: {
    database: '<database>',
    query: 'SHOW SCHEMAS',
  },
  connector: 'cockroachdbmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="cockroachdbmcp_explain_query",
    tool_input={
        "database": "<database>",
        "query": "SHOW SCHEMAS",
    },
    connection_name="cockroachdbmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `cockroachdbmcp_explain_query`

Explain query · Read-only

Show query execution plan without executing the query

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `query` (`string`, required): The SQL query to explain
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{"database":"<database>","query":"SHOW SCHEMAS"}`

### `cockroachdbmcp_get_cluster`

Get cluster · Read-only

Get detailed information for the CockroachDB cluster

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{}`

### `cockroachdbmcp_get_table_schema`

Get table schema · Read-only

Get detailed schema information for a table including columns and indexes

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `table` (`string`, required): The name of the table
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.
- `schema` (`string`, optional): The schema name (defaults to 'public' if not specified)

Example input: `{"database":"<database>","table":"<table>"}`

### `cockroachdbmcp_list_clusters`

List clusters · Read-only

List all CockroachDB clusters accessible to the authorized user

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `show_inactive` (`boolean`, optional): If true, show clusters that have been deleted or failed to initialize. Default: `false`.

Example input: `{}`

### `cockroachdbmcp_list_databases`

List databases · Read-only

List all databases in the CockroachDB cluster.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.
- `limit` (`integer`, optional): Maximum results to return (default: 100, max: 10000). Default: `100`.
- `offset` (`integer`, optional): Number of results to skip (default: 0). Default: `0`.

Example input: `{}`

### `cockroachdbmcp_list_tables`

List tables · Read-only

List all tables in a database.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.
- `limit` (`integer`, optional): Maximum results to return (default: 100, max: 10000). Default: `100`.
- `offset` (`integer`, optional): Number of results to skip (default: 0). Default: `0`.

Example input: `{"database":"<database>"}`

### `cockroachdbmcp_select_query`

Select query · Read-only

Execute a read-only SELECT query on the CockroachDB cluster.
Automatically adds LIMIT 25 if not specified. Maximum LIMIT is 10000.
Use LIMIT with OFFSET for pagination (e.g., LIMIT 100 OFFSET 200).

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `query` (`string`, required): The SQL query to execute (SELECT statements only). Use LIMIT/OFFSET in your query for pagination.
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{"database":"<database>","query":"SHOW SCHEMAS"}`

### `cockroachdbmcp_show_running_queries`

Show running queries · Read-only

List currently executing queries on the cluster

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{}`

### `cockroachdbmcp_show_statement`

Show statement · Read-only

Execute a SHOW statement for introspection (e.g., SHOW SCHEMAS, SHOW INDEXES, SHOW REGIONS, SHOW CONSTRAINTS).
Results are limited to 100 rows by default. Prefer list_databases, list_tables, or get_table_schema for those operations.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `query` (`string`, required): The SHOW statement to execute (e.g., 'SHOW SCHEMAS', 'SHOW INDEXES FROM mytable', 'SHOW REGIONS', 'SHOW CREATE TABLE mytable', 'SHOW CONSTRAINTS FROM mytable')
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.
- `database` (`string`, optional): The database context for the SHOW statement (optional for cluster-level statements like SHOW DATABASES)

Example input: `{"query":"SHOW SCHEMAS"}`

### `cockroachdbmcp_create_database`

Create database · Write

Create a new database in the cluster

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `database` (`string`, required): The name of the database to create
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{"database":"<database>"}`

### `cockroachdbmcp_create_table`

Create table · Write

Create a new table in a database using a CREATE TABLE DDL statement. Only CREATE TABLE statements are allowed. Supports CREATE TABLE AS SELECT for creating tables from query results.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `ddl` (`string`, required): The CREATE TABLE DDL statement
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{"database":"<database>","ddl":"<ddl>"}`

### `cockroachdbmcp_insert_rows`

Insert rows · Destructive

Insert rows into an existing table. Only INSERT statements are allowed, including INSERT INTO ... VALUES and INSERT INTO ... SELECT.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `database` (`string`, required): The name of the database
- `query` (`string`, required): The INSERT statement to execute. Include the full table name with optional schema prefix (e.g., 'INSERT INTO schema.table_name ...' or 'INSERT INTO table_name ...').
- `cluster_id` (`string`, optional): CockroachDB cluster UUID. Required when the MCP config has no cluster_id; otherwise must be omitted.

Example input: `{"database":"<database>","query":"INSERT INTO schema.table_name ..."}`

## Related

Other Databases connectors ([all 39](/agentkit/connectors/?category=databases)):

- [AWS Redshift](/agentkit/connectors/redshift/): Scalekit connector, Trusted identity provider, 10 tools
- [Google BigQuery](/agentkit/connectors/bigquery/): Scalekit connector, OAuth, 47 tools
- [Airtable](/agentkit/connectors/airtable/): Scalekit connector, OAuth, 26 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
