ClickStack MCP 服务器

ClickStack 内置了 Model Context Protocol (MCP) 服务器，让 AI 助手能够与你的可观测性数据交互。连接后，AI 助手可以通过自然语言查询日志、链路追踪和指标；管理仪表盘和告警；浏览数据源；以及使用已保存的搜索。

这样一来，你就可以使用 Claude Code、Cursor 或任何兼容 MCP 的客户端，在不离开开发环境的情况下排查故障、构建仪表盘并管理你的可观测性配置。

MCP 服务器可用于以下 ClickStack 部署类型：

ClickHouse Cloud 上的 ClickStack 通过 Cloud MCP 端点 https://mcp.clickhouse.cloud/clickstack 连接，并使用 OAuth 2.0 进行身份验证。该端点不支持 API key 身份验证。

• 一个正在运行且已启用 ClickStack的 ClickHouse Cloud 服务
• 服务上已启用 MCP——打开 Cloud 控制台，点击 Connect，选择 Connect with MCP，然后将其切换为开启状态

https://mcp.clickhouse.cloud/clickstack

身份验证采用 OAuth 2.0。首次连接时，MCP 客户端会打开浏览器窗口，供你使用 ClickHouse Cloud 凭据登录。无需 API 密钥。

每个客户端在首次连接时都会自动处理 OAuth 流程。

claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack

{
  "mcpServers": {
    "clickstack": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

{
  "servers": {
    "clickstack": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

{
  "mcp": {
    "clickstack": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/clickstack

如果未提供 x-service-id 请求头，请求默认会发送到你账户中第一个已预配并使用的 ClickStack 服务。若要指定其他服务，请在 MCP 客户端配置中将 x-service-id: <YOUR_SERVICE_ID> 作为请求头传入。

开源和 BYOC 部署使用您的 ClickStack 实例内置的 MCP 端点，并采用 Bearer 令牌身份验证。

• 一个正在运行的 ClickStack 实例 (有关设置选项，请参见 部署)
• 一个 Personal API Access Key — 您可以在 HyperDX 的 Team Settings → API Keys → Personal API Access Key 中找到

可通过 ClickStack 前端 URL 上的 /api/mcp 路径访问 MCP 服务器。例如，使用默认本地部署时，URL 为 http://localhost:8080/api/mcp。如果你修改了默认设置，请将 localhost:8080 替换为你的实例主机和端口。

MCP 服务器 使用 Streamable HTTP 传输和 Bearer token 身份验证。

将 <YOUR_CLICKSTACK_URL> 替换为你的实例 URL (例如 http://localhost:8080) ，并将 <YOUR_API_KEY> 替换为你的 Personal API Access Key。

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "servers": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "mcp": {
    "hyperdx": {
      "type": "remote",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: <YOUR_CLICKSTACK_URL>/api/mcp
    headers:
      Authorization: "Bearer <YOUR_API_KEY>"

连接后，你的 AI 助手可以访问覆盖 ClickStack 核心领域的一系列工具，包括：

• 查询数据 — 使用 ClickStack 的查询构建器、搜索语法或原生 SQL，对日志、链路追踪和指标进行搜索与聚合。
• 数据源 — 列出可用的数据源、数据库连接、列 schema 和属性键。
• 仪表盘 — 创建、更新、删除和查看仪表盘及其卡片。
• 告警 — 创建、更新和查看告警及其评估历史。
• 已保存的搜索 — 创建、更新和查看可复用的已保存搜索定义。
• Webhooks — 列出可用于告警通知的 webhook 目标端。
• 团队 — 列出当前用户所属的团队，并识别当前活动团队。

具体可用的工具集可能会随时间不断扩展。MCP 客户端 会在连接时自动发现可用工具。

这仅适用于 开源和 BYOC 部署。对于 ClickHouse Cloud 上的 ClickStack，请参阅指定特定服务。

默认情况下，MCP 请求会在你的主团队上下文中处理。如果你属于多个团队，可以在传递 Authorization 请求头的同时，添加一个值为该团队 ID 的 x-hdx-team 请求头，以指定特定团队。如果省略该请求头，则会使用你的主团队。如果你指定了一个自己不属于的团队，请求会被拒绝，并返回 401 错误。

使用 MCP 客户端 中的团队列表工具，查看你可以访问哪些团队以及当前处于活动状态的是哪个团队。