CockroachDB Plugin for Cursor

Connect to any CockroachDB cluster (Cloud, self-hosted, local) via MCP Toolbox for Databases.

Install: brew install mcp-toolbox (v1.0.0+)

Run (stdio, default): toolbox --config tools.yaml --stdio

Run (HTTP): toolbox --config tools.yaml --address 0.0.0.0 --port 5000

Run (with web UI): toolbox --config tools.yaml --ui --port 5000 (opens at http://127.0.0.1:5000/ui)

Note: Toolbox must successfully connect to CockroachDB on startup. If the database is unreachable (wrong host/port, env vars not set), the server will hang during initialization and the UI will be stuck on "Fetching tools...". Make sure your COCKROACHDB_* environment variables are set and the database is accessible before starting.

The ccloud CLI is an agent-ready command-line tool for full cluster lifecycle management. AI agents call ccloud directly via shell commands (not MCP protocol) -- every command supports -o json for structured output.

Install: brew install cockroachdb/tap/ccloud

Authenticate (interactive): ccloud auth login (opens browser; supports SSO via OIDC/SAMLv2)

Authenticate (org-scoped): ccloud auth login --org {organization-label}

Authenticate (headless/CI): ccloud auth login --no-redirect or use a service account API key as a bearer token.

Example agent commands:

# Provision
ccloud cluster create serverless my-cluster us-east-1 --cloud AWS -o json
ccloud cluster database create my-cluster myapp -o json

# Connect
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json
# Composable: pipe into jq + psql
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json \
  | jq -r '.connection_url' | xargs -I{} psql {} -c "SELECT count(*) FROM users"

# Operate
ccloud cluster list -o json
ccloud cluster info my-cluster -o json
ccloud cluster backup config update my-cluster --frequency 60 --retention 60

# Observe
ccloud audit list --limit 10 -o json
ccloud cluster versions -o json
ccloud cluster cmek get my-cluster -o json

# Scale & DR
ccloud replication create --primary-cluster prod-east --standby-cluster dr-west
ccloud cluster networking allowlist list <cluster-id> -o json

# Organize
ccloud folder create Production -o json
ccloud folder contents <folder-id> -o json

# Test resilience
ccloud cluster disruption set my-cluster --region us-east-1 --whole-region

Coverage: Provision, Connect, Operate, Observe, Scale & DR, Organize, Test resilience. See the ccloud reference for full command list.

The official managed MCP server is hosted by Cockroach Labs and requires no infrastructure setup. Authenticate via OAuth 2.1 (PKCE) or a service account API key. Read-only by default; write access requires explicit consent.

OAuth (recommended — opens browser for consent, scopes: mcp:read, mcp:write):

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

API Key (headless/autonomous agents):

{
  "mcpServers": {
    "cockroachdb-cloud": {
      "type": "http",
      "url": "https://cockroachlabs.cloud/mcp",
      "headers": {
        "mcp-cluster-id": "{your-cluster-id}",
        "Authorization": "Bearer {your-service-account-api-key}"
      }
    }
  }
}

See the quickstart guide for detailed setup.