From 40684d04501c29e9c10bc3a38b221422e591b820 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Jun 2026 19:08:49 +0000 Subject: [PATCH] docs: port ClickStack MCP Cloud setup from upstream PR #6368 --- clickstack/mcp.mdx | 197 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 168 insertions(+), 29 deletions(-) diff --git a/clickstack/mcp.mdx b/clickstack/mcp.mdx index 6230b7749..52c111c42 100644 --- a/clickstack/mcp.mdx +++ b/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'ClickStack MCP server' sidebarTitle: 'MCP Server' description: 'Connect AI assistants to ClickStack using the Model Context Protocol (MCP) server' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'observability', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'observability', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -21,18 +21,111 @@ The MCP server is available in the following ClickStack deployment types: |---|---| | **Open Source ClickStack** | Available | | **BYOC (Bring Your Own Cloud)** | Available | -| **Managed ClickStack** | Coming soon | +| **ClickStack on ClickHouse Cloud** | Available | | **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Not supported | - -**Managed ClickStack** + +**Different setup for ClickHouse Cloud vs OSS/BYOC** + +ClickStack on ClickHouse Cloud uses a different endpoint and authentication method than Open Source and BYOC deployments. See the [ClickStack on ClickHouse Cloud](#managed-clickstack) section below for Cloud-specific setup. + + +## ClickStack on ClickHouse Cloud {#managed-clickstack} + +ClickStack on ClickHouse Cloud connects through the Cloud MCP endpoint at `https://mcp.clickhouse.cloud/clickstack` and authenticates with OAuth 2.0. API key authentication is not supported for this endpoint. + +### Prerequisites {#managed-prerequisites} + +- A running ClickHouse Cloud service with [ClickStack enabled](/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud) +- [MCP enabled](/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) on the service — open the Cloud console, click **Connect**, select **Connect with MCP**, and toggle it on + +### Endpoint {#managed-endpoint} + +```text +https://mcp.clickhouse.cloud/clickstack +``` + +Authentication uses OAuth 2.0. When your MCP client connects for the first time, it opens a browser window for you to sign in with your ClickHouse Cloud credentials. No API key is needed. + +### Connecting an MCP client {#managed-connecting-a-client} + +Each client handles the OAuth flow automatically on first connection. + + + + +```shell +claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack +``` + +Launch Claude Code and run `/mcp`, then select `clickstack-cloud` to complete the OAuth flow. + + + + +Add the following to `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } +} +``` + + + + +Add the following to `.vscode/mcp.json`: + +```json +{ + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } +} +``` + + + -MCP server support for Managed ClickStack is under active development and will be available soon. The instructions on this page apply to Open Source and BYOC deployments. - +Add the following to `opencode.json`: -## Prerequisites {#prerequisites} +```json +{ + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } +} +``` + + + + +Any MCP client that supports **Streamable HTTP** with OAuth can connect. Configure it with: + +- **URL:** `https://mcp.clickhouse.cloud/clickstack` -Before connecting an MCP client, you need: + + + +### Targeting a specific service {#managed-service-override} + +Without the `x-service-id` header, requests default to the first ClickStack service provisioned and used by your account. To target a different service, pass `x-service-id: ` as a header in your MCP client configuration. + +## Open Source and BYOC {#oss-byoc} + +Open Source and BYOC deployments use your ClickStack instance's built-in MCP endpoint with Bearer token authentication. + +### Prerequisites {#oss-prerequisites} - A running ClickStack instance (see [Deployment](/clickstack/deployment/overview) for setup options) - A **Personal API Access Key** — find yours in HyperDX under **Team Settings → API Keys → Personal API Access Key** @@ -43,13 +136,9 @@ Before connecting an MCP client, you need: The Personal API Access Key is different from the **Ingestion API Key** found in Team Settings, which is used to authenticate telemetry data sent to the OpenTelemetry collector. -## Endpoint {#endpoint} +### Endpoint {#oss-endpoint} -The MCP server is available at the `/api/mcp` path on your ClickStack frontend URL: - -For example, with a default local deployment: - -Replace `localhost:8080` with your instance's host and port if you have customized the defaults. +The MCP server is available at the `/api/mcp` path on your ClickStack frontend URL. For example, with a default local deployment, the URL is `http://localhost:8080/api/mcp`. Replace `localhost:8080` with your instance's host and port if you've customized the defaults. The examples on this page use the frontend app URL (port `8080` by default). You can also reach the MCP server directly via the backend at `/mcp`, but not all deployments expose the backend, so these docs use the frontend path. @@ -57,20 +146,22 @@ The examples on this page use the frontend app URL (port `8080` by default). You The MCP server uses the **Streamable HTTP** transport with **Bearer token** authentication. -## Connecting an MCP client {#connecting-a-client} +### Connecting an MCP client {#oss-connecting-a-client} -The examples below show how to configure popular MCP clients. Replace `` with your instance URL (for example, `http://localhost:8080`) and `` with your Personal API Access Key. +Replace `` with your instance URL (for example, `http://localhost:8080`) and `` with your Personal API Access Key. -### Claude code {#claude-code} + + ```shell claude mcp add --transport http hyperdx /api/mcp \ --header "Authorization: Bearer " ``` -### Cursor {#cursor} + + -Add the following to `.cursor/mcp.json` in your project or your global Cursor settings: +Add the following to `.cursor/mcp.json`: ```json { @@ -85,16 +176,39 @@ Add the following to `.cursor/mcp.json` in your project or your global Cursor se } ``` -### OpenCode {#opencode} + + -Add the following to your `opencode.json` config: +Add the following to `.vscode/mcp.json`: + +```json +{ + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } +} +``` + + + + +Add the following to `opencode.json`: ```json { "mcp": { "hyperdx": { - "type": "http", + "type": "remote", "url": "/api/mcp", + "oauth": false, "headers": { "Authorization": "Bearer " } @@ -103,13 +217,17 @@ Add the following to your `opencode.json` config: } ``` -### Other clients {#other-clients} + + -Any MCP client that supports the **Streamable HTTP** transport can connect. Configure it with: +Any MCP client that supports **Streamable HTTP** can connect. Configure it with: - **URL:** `/api/mcp` - **Header:** `Authorization: Bearer ` + + + ## What can you do with MCP? {#capabilities} Once connected, your AI assistant has access to a range of tools spanning the core areas of ClickStack. These include: @@ -124,22 +242,43 @@ Once connected, your AI assistant has access to a range of tools spanning the co The specific set of tools may expand over time. Your MCP client will automatically discover the available tools when it connects. -## Multi-team usage {#multi-team} +## Multi-team usage (OSS/BYOC) {#multi-team} -By default, MCP requests operate in the context of your primary team. If you belong to multiple teams, you can target a specific team by passing the `x-hdx-team` header set to the team's ID alongside your `Authorization` header. If the header is omitted, your primary team is used. If you specify a team you don't belong to, the request is rejected with a `401` error. +This applies to Open Source and BYOC deployments only. For ClickStack on ClickHouse Cloud, see [Targeting a specific service](#managed-service-override). + +By default, MCP requests operate in the context of your primary team. If you belong to multiple teams, pass the `x-hdx-team` header set to the team's ID alongside your `Authorization` header. If the header is omitted, your primary team is used. If you specify a team you don't belong to, the request is rejected with a `401` error. Use the team listing tool from your MCP client to discover which teams you have access to and which one is active. ## Troubleshooting {#troubleshooting} +### ClickStack on ClickHouse Cloud {#troubleshooting-managed} + + +- Confirm your MCP client supports OAuth 2.0. Clients that only support Bearer token or stdio transport can't authenticate with the Cloud endpoint. +- Check that your browser isn't blocking the OAuth popup or redirect. +- Verify your ClickHouse Cloud account has access to the organization and service. + + + +- Confirm you're using the ClickStack endpoint (`https://mcp.clickhouse.cloud/clickstack`), not the general Cloud MCP endpoint (`https://mcp.clickhouse.cloud/mcp`). +- Verify that [MCP is enabled](/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) on the service in the Cloud console. + + + +Without the `x-service-id` header, requests default to the first ClickStack service provisioned and used by your account. Pass the header to target a specific service. See [Targeting a specific service](#managed-service-override). + + +### Open Source and BYOC {#troubleshooting-oss} + -- Verify that you are using the **Personal API Access Key** (not the Ingestion API Key). +- Verify that you're using the **Personal API Access Key** (not the Ingestion API Key). - Confirm the key is included as a `Bearer` token in the `Authorization` header. - Check that your ClickStack instance is running and reachable at the URL you configured. -The MCP server enforces a rate limit of **600 requests per minute** per user. If you exceed this limit, requests will be temporarily rejected. Reduce the frequency of requests or wait before retrying. +The MCP server enforces a rate limit of **600 requests per minute** per user. If you exceed this limit, requests are temporarily rejected. Reduce the frequency of requests or wait before retrying. @@ -148,6 +287,6 @@ Verify that the team ID is correct and that your user account is a member of tha - Ensure your MCP client supports the **Streamable HTTP** transport. Older clients that only support the stdio transport won't work. -- If you are running ClickStack locally, confirm the app is accessible at the configured URL (the default is `http://localhost:8080`). +- If you're running ClickStack locally, confirm the app is accessible at the configured URL (the default is `http://localhost:8080`). - For BYOC deployments behind a load balancer or reverse proxy, ensure the `/api/mcp` path isn't being blocked or rewritten.