diff --git a/docs/use-cases/observability/clickstack/mcp.md b/docs/use-cases/observability/clickstack/mcp.md index 6f34587fb05..c198feb2455 100644 --- a/docs/use-cases/observability/clickstack/mcp.md +++ b/docs/use-cases/observability/clickstack/mcp.md @@ -6,10 +6,12 @@ pagination_prev: null pagination_next: null 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 '@theme/IdealImage'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import api_key from '@site/static/images/clickstack/api-key-personal.png'; ClickStack includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants interact with your observability data. Once connected, an AI assistant can query logs, traces, and metrics; manage dashboards and alerts; explore data sources; and work with saved searches — all through natural language. @@ -24,16 +26,109 @@ 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 | -:::note[Managed 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. +:::note[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. ::: -## Prerequisites {#prerequisites} +## ClickStack on ClickHouse Cloud {#managed-clickstack} -Before connecting an MCP client, you need: +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" + } + } +} +``` + + + + +Add the following to `opencode.json`: + +```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` + + + + +### 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](/use-cases/observability/clickstack/deployment) for setup options) - A **Personal API Access Key** — find yours in HyperDX under **Team Settings → API Keys → Personal API Access Key** @@ -44,13 +139,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} - -The MCP server is available at the `/api/mcp` path on your ClickStack frontend URL: - -For example, with a default local deployment: +### Endpoint {#oss-endpoint} -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. :::note 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. @@ -58,20 +149,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 { @@ -86,13 +179,14 @@ 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", @@ -104,13 +198,37 @@ Add the following to your `opencode.json` config: } ``` -### Other clients {#other-clients} + + + +Add the following to `opencode.json`: + +```json +{ + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + + + -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: @@ -125,18 +243,48 @@ 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} + +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, 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. +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} + +
+OAuth flow doesn't complete + +- 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. + +
+ +
+MCP is enabled but the client can't connect + +- 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. + +
+ +
+Requests go to the wrong service + +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} +
I'm getting a 403 authentication error -- 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. @@ -145,7 +293,7 @@ Use the team listing tool from your MCP client to discover which teams you have
I'm being rate limited -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.
@@ -160,7 +308,7 @@ Verify that the team ID is correct and that your user account is a member of tha I can't connect to the MCP server - 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.