CockroachDB Plugin for GitHub Copilot

Connect GitHub Copilot directly to your CockroachDB clusters for hands-on database work: explore schemas, write optimized SQL, debug queries, and manage distributed database clusters. This plugin provides tools across MCP backends (self-hosted MCP Toolbox and managed CockroachDB Cloud MCP Server), specialized agents (DBA, Developer, Operator), skills across operational domains, and built-in safety hooks.

Installation

Install from a plugin marketplace. VS Code reads the copilot-plugins and awesome-copilot marketplaces by default; add this repository with the chat.plugins.marketplaces setting, then open the Extensions view, search @agentPlugins, and install the cockroachdb plugin.

Install from source

Run Chat: Install Plugin From Source from the Command Palette and point it at this repository, or with the Copilot CLI:

copilot plugin install cockroachdb/copilot-plugin

Use as workspace customizations

Clone the repository into your project. Copilot reads .github/skills, .github/agents, and .github/hooks directly, and .vscode/mcp.json provides the cluster connection.

Prerequisites

The skills, agents, and hooks work without any setup. Each of the plugin's MCP servers needs its own:

• cockroachdb-toolbox (any self-hosted or Cloud cluster) needs MCP Toolbox for Databases v1.0.0 or later on your PATH, and a running CockroachDB cluster it can reach. Toolbox connects when the session starts, so without a reachable cluster this server fails to start. If you don't run a cluster, turn the server off.
• cockroachdb-cloud (CockroachDB Cloud) needs a CockroachDB Cloud account, and signs in with OAuth through your browser.

Install MCP Toolbox

macOS or Linux:

brew install mcp-toolbox

Windows: download toolbox.exe into a folder on your PATH. In PowerShell, set the version to the latest one on the Toolbox releases page, and use windows/arm64 in the URL on Arm devices:

$VERSION = "1.14.0"
curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/amd64/toolbox.exe"

Restart VS Code or your terminal after changing your PATH, then confirm the install with toolbox --version. For other platforms, the container image, and building from source, see Install Toolbox.

Configuration

Self-hosted clusters (MCP Toolbox)

The cockroachdb-toolbox server reads its connection settings from environment variables, which Copilot passes through to it. Each one is optional, and an unset variable falls back to the default in tools.yaml:

Variable	Default	Notes
COCKROACHDB_HOST	localhost
COCKROACHDB_PORT	26257
COCKROACHDB_USER	root
COCKROACHDB_PASSWORD	(empty)
COCKROACHDB_DATABASE	defaultdb
COCKROACHDB_SSLMODE	require	Use disable for a local --insecure cluster, verify-full for production

Set them in the environment Copilot starts from. On macOS or Linux, add them to your shell profile:

export COCKROACHDB_HOST="your-cluster-host"
export COCKROACHDB_PORT="26257"
export COCKROACHDB_USER="your-user"
export COCKROACHDB_PASSWORD="your-password"
export COCKROACHDB_DATABASE="your-database"
export COCKROACHDB_SSLMODE="verify-full"

On Windows, set them as user environment variables, for example setx COCKROACHDB_HOST "your-cluster-host", then restart VS Code or your terminal.

For a CockroachDB Cloud cluster, find the connection details in the Cloud Console.

Toolbox runs in read-only mode: SELECT, SHOW, and EXPLAIN work, and writes and schema changes are rejected. To allow writes, run Toolbox with your own copy of tools.yaml that sets enableWriteMode: true, configured as your own MCP server, and turn off the plugin's cockroachdb-toolbox server.

CockroachDB Cloud

The cockroachdb-cloud server connects to the managed MCP server that Cockroach Labs hosts. The consent screen asks you to grant read access, write access, or both. The connection can reach every cluster your CockroachDB Cloud role allows.

To limit a connection to one cluster, add your own server entry with an mcp-cluster-id header, as shown under Alternative MCP Backends. When you open this repository as a workspace, .vscode/mcp.json sends the header with COCKROACHDB_CLUSTER_ID if you set it.

Turn off a server you don't use

Copilot starts both MCP servers in every session. If you only use one of them, turn off the other:

• Copilot CLI: run /mcp disable cockroachdb-toolbox (or cockroachdb-cloud) in a session, and the choice persists across sessions. To skip a server for a single session, start Copilot with --disable-mcp-server cockroachdb-toolbox.
• VS Code: in the Extensions view, right-click the server under MCP SERVERS - INSTALLED and select Disable.

MCP configuration files

The plugin ships two MCP configs, because Copilot uses different keys in each context:

• .mcp.json (top-level mcpServers) is read when the plugin is installed from a marketplace.
• .vscode/mcp.json (top-level servers) is read when the repository is opened as a workspace.

The default backend is the MCP Toolbox over stdio. The managed CockroachDB Cloud MCP Server is also configured.

Alternative MCP Backends

CockroachDB Cloud MCP Server (OAuth/API key)

The official managed MCP server is hosted by Cockroach Labs and requires no infrastructure setup. The plugin already includes it as cockroachdb-cloud; add your own entry to limit it to one cluster or to use a service account API key. With OAuth 2.1 (PKCE), the consent screen asks you to grant read access, write access, or both (scopes mcp:read and mcp:write).

Give your entry its own name, such as cockroachdb-cloud-cluster, so it doesn't clash with the plugin's cockroachdb-cloud server, and turn the plugin's server off. In VS Code (mcp.json):

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

With the Copilot CLI:

copilot mcp add --transport http cockroachdb-cloud-cluster https://cockroachlabs.cloud/mcp --header "mcp-cluster-id: {your-cluster-id}"

Leave out the mcp-cluster-id header to reach every cluster your user or service account can access. For headless or autonomous agents, add an Authorization: Bearer {your-service-account-api-key} header. See the quickstart guide for detailed setup.

CockroachDB MCP Server (first-party, self-hosted)

CockroachDB MCP Server is Cockroach Labs' own MCP server for clusters you run yourself. By default it registers only read-only tools, such as list_databases, list_tables, get_table_schema, select_query, explain_query, show_statement, and show_running_queries. Setting CRDB_MCP_ENABLE_WRITE_QUERIES=true adds create_database, create_table, insert_rows, update_rows, and delete_rows, and the server refuses an UPDATE or DELETE without a WHERE clause.

Install: go install github.com/cockroachdb/cockroachdb-mcp-server@latest (Go 1.26+). Linux and Windows binaries and a Docker image are listed on the releases page. There are no prebuilt macOS binaries, so on macOS use go install or Docker.

Configure with certificate authentication (recommended). In VS Code (mcp.json):

{
  "servers": {
    "cockroachdb-mcp-server": {
      "command": "cockroachdb-mcp-server",
      "env": {
        "CRDB_HOST": "your-cluster-host",
        "CRDB_USERNAME": "ai_agent",
        "CRDB_SSL_MODE": "verify-full",
        "CRDB_SSL_CA_PATH": "/certs/ca.crt",
        "CRDB_SSL_CERTFILE": "/certs/client.ai_agent.crt",
        "CRDB_SSL_KEYFILE": "/certs/client.ai_agent.key"
      }
    }
  }
}

For a local --insecure development cluster with the Copilot CLI:

copilot mcp add cockroachdb-mcp-server --env CRDB_DATABASE_URL="postgresql://root@localhost:26257/defaultdb?sslmode=disable" --env CRDB_MCP_ALLOW_INSECURE_DB=true -- cockroachdb-mcp-server

Password authentication is off unless you set CRDB_MCP_ALLOW_PASSWORD_AUTH=true. If the server doesn't start, give the binary's absolute path as the command, since apps launched outside a terminal may not search ~/go/bin. The plugin's SQL safety hook applies to the bundled Toolbox server; this server enforces its own guardrails. See the server's README for every setting.

ccloud CLI (cluster lifecycle, backups, DR, networking)

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

Install: brew install cockroachdb/tap/ccloud

See the ccloud reference for the full command list.

What's Included

MCP Backends

Backend	Status	Transport	Use Case
cockroachdb-toolbox	Active	stdio	Any CockroachDB cluster via MCP Toolbox
cockroachdb-cloud	Active	Streamable HTTP	Managed MCP Server, CockroachDB Cloud (OAuth/API key)
cockroachdb-mcp-server	Available	stdio, HTTPS	First-party server for self-hosted clusters (not shipped; add it yourself, see Alternative MCP Backends)

Skills

Skills are sourced from the cockroachdb-skills submodule, a single source of truth shared across CockroachDB agent integrations. Copilot requires a flat skill layout, so scripts/sync-skills.sh flattens the domain-grouped upstream tree into .github/skills/<skill>/. A weekly CI workflow auto-detects upstream changes and opens a PR to update.

Domain	Examples
Query & Schema Design	cockroachdb-sql
Observability & Diagnostics	profiling-statement-fingerprints, triaging-live-sql-activity
Security & Governance	auditing-cloud-cluster-security, hardening-user-privileges
Onboarding & Migrations	molt-fetch, molt-verify, molt-replicator
Operations & Lifecycle	managing-cluster-capacity, upgrading-cluster-version

Agents

Agent	Description
cockroachdb-dba	CockroachDB DBA expert: performance tuning, schema review, cluster diagnostics
cockroachdb-developer	Application developer expert: ORM config, retry logic, transaction patterns
cockroachdb-operator	Operator/SRE expert: cluster operations, monitoring, backups, scaling, incidents

Agents are discovered from .github/agents/. Copilot selects them based on task context, or you can pick one from the agent picker in agent mode.

Hooks

Hook	Trigger	What It Does
validate-sql	Before SQL execution	Blocks DROP DATABASE, TRUNCATE; warns on SERIAL, multi-DDL transactions
check-sql-files	After a file edit	Scans SQL/code files for CockroachDB anti-patterns (SERIAL, SELECT *, missing retry)

Hooks run as Python scripts (Python 3, no external dependencies) and provide automated safety guardrails. VS Code runs hooks on every tool invocation regardless of the matcher, and the scripts exit early when the input is not relevant.

Windows note: the hooks invoke python3, so make sure a python3 is on your PATH. The python.org installer creates python.exe and the py launcher but not python3.exe; on those installs the hooks safely no-op (they never block editing, but the safety checks will not run). Installing Python from the Microsoft Store, or adding a python3 alias, enables them. You do not need to turn on Windows long-path support: the hooks load their scripts through the \\?\ long-path prefix, so they work no matter how deep the plugin cache path is.

Development

Clone the repository:

git clone --recurse-submodules https://github.com/cockroachdb/copilot-plugin.git
cd copilot-plugin

Resync skills from the submodule after an update:

scripts/sync-skills.sh submodules/cockroachdb-skills/skills

Project Structure

plugin.json                      # Plugin manifest (Copilot agent plugin)
.mcp.json                        # MCP server config for plugin installs (mcpServers)
.vscode/mcp.json                 # MCP server config for workspace use (servers)
tools.yaml                       # Toolbox source & tool definitions
.github/
  plugin/marketplace.json        # Marketplace catalog for distribution
  agents/
    cockroachdb-dba.agent.md     # DBA agent
    cockroachdb-developer.agent.md
    cockroachdb-operator.agent.md
  hooks/
    cockroachdb.json             # Hook configuration
  skills/                        # Skills flattened from the cockroachdb-skills submodule
  workflows/
    update-skills.yml            # Weekly submodule sync
    release-please.yml           # Automated releases
scripts/
  validate-sql.py                # SQL validation hook
  check-sql-files.py             # Anti-pattern linter hook
  sync-skills.sh                 # Flatten skills into the Copilot layout
submodules/
  cockroachdb-skills/            # Shared skills submodule
assets/
  logo.svg                       # Plugin logo

Releasing

This repo uses Release Please for automated releases.

1. Use Conventional Commits (feat:, fix:) on main
2. Release Please opens a Release PR with version bump and changelog
3. Merge the Release PR to publish

Links

• CockroachDB Documentation
• CockroachDB Cloud Console
• Managed MCP Server Blog Post
• Cloud MCP Quickstart Guide
• Agent Skills in VS Code
• Agent Plugins in VS Code
• MCP Toolbox for Databases
• Report Issues

License

Apache-2.0