Docs for CockroachDB MCP Server Phase 1#22885
Docs for CockroachDB MCP Server Phase 1#22885bsanchez-the-roach wants to merge 4 commits intomainfrom
Conversation
Files changed:
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
| "type": "http", | ||
| "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}" | ||
| } | ||
| ~~~ |
There was a problem hiding this comment.
It would be helpful if an engineer could go through and make sure that all eight of these JSON snippets are accurate. I just copied the OAuth ones from the instructions on the cluster connect modal. For the API key ones, I simply added the Authentication header, as in the Claude Code config, but that might not be the right syntax for all of the other tools.
| "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}" | ||
| } | ||
| ~~~ | ||
|
|
There was a problem hiding this comment.
Also, in the first published version of this document, do we actually want to do JSON snippets or would we rather include the CLI commands for each tool?
| 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. | ||
|
|
There was a problem hiding this comment.
It would also be helpful if, for each of these tools, an engineer could give me the command to run to verify that the server has been added correctly, and (perhaps a separate?) command to verify that the connection is working. For example claude mcp list shows that the server has been added to claude (though I don't know what the command is to verify the connection, if there is one).
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| - [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. |
There was a problem hiding this comment.
Can we mention OAuth first here, with a note that its recommended? Since, OAuth is more secure to connect with short lived tokens, as compared to API key (long lived token).
|
|
||
| ## Step 2. Update tool configuration | ||
|
|
||
| Cockroach Labs enables access to its CockroachDB Cloud MCP server via HTTP. |
There was a problem hiding this comment.
| Cockroach Labs enables access to its CockroachDB Cloud MCP server via HTTP. | |
| Cockroach Labs enables access to its CockroachDB Cloud MCP server via HTTP transport. |
|
|
||
| 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**. |
There was a problem hiding this comment.
Here, the user will see an Organization Selection modal, in case they are part of multiple orgs. Its worth mentioning that.
| "headers": { | ||
| "Authorization": "Bearer {your-service-account-api-key}" | ||
| } | ||
| } |
There was a problem hiding this comment.
We have moved clusterID from query params to header, to keep it consistent across all the tools. So, this will need to be updated to:
"cockroachdb-cloud": {
"type": "http",
"url": "https://cockroachlabs.cloud/mcp",
"headers": {
"mcp-cluster-id": "{your-cluster-id}"
}
}
| } | ||
| ~~~ | ||
|
|
||
| 2. Open `.claude.json`. |
There was a problem hiding this comment.
We have also updated these steps, based on internal testing and to make the onboarding easier. Please refer this PR: https://github.com/cockroachlabs/managed-service/pull/23407. I will try to get these changes in staging by tomorrow (5th March) for your reference.
| | `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. | |
There was a problem hiding this comment.
We are updating this tool name to "select_query" to keep it consistent with "explain_query" and to avoid LLM hallucinating for other read operations.
|
|
||
| 2. Open `.cursor/mcp.json`. | ||
|
|
||
| 3. Find `"mcpServers"`. Include the JSON snippet in the list of MCP servers, replacing the `{your-cluster-id}` placeholder. |
There was a problem hiding this comment.
For cursor and github copilot, we can add a single click installation button. Refer: https://github.com/cockroachlabs/managed-service/pull/23407
|
|
||
| ~~~json | ||
| "cockroachdb-cloud": { | ||
| "url": "https://cockroachlabs.cloud/mcp?cluster_id={your-cluster-id}", |
There was a problem hiding this comment.
Same here and other other configs below, we are moving cluster_id from query param to header:
"cockroachdb-cloud": {
"url": "https://cockroachlabs.cloud/mcp",
"headers": {
"Authorization": "Bearer {your-service-account-api-key}",
"mcp-cluster-id": "{your-cluster-id}"
}
}
2 participants
DOC-15457
For now this is just a "Getting Started" guide.