ClickStack MCP 服务器

通过 Model Context Protocol (MCP) 服务器将 AI 助手连接到 ClickStack

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

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

​

可用性

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

部署	状态
开源 ClickStack	可用
BYOC (自备 Cloud)	可用
ClickHouse Cloud 上的 ClickStack	可用
HyperDX v1 (hyperdx.io)	不支持

ClickHouse Cloud 与 OSS/BYOC 的设置差异

ClickHouse Cloud 上的 ClickStack 使用的端点和身份验证方法与开源和 BYOC 部署不同。有关 Cloud 专用设置，请参阅下方的 ClickHouse Cloud 上的 ClickStack 部分。

​

ClickHouse Cloud 上的 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 密钥。

​

连接 MCP 客户端

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

Claude Code

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

启动 Claude Code 并运行 /mcp，然后选择 clickstack 以完成 OAuth 流程。

Cursor

将以下内容添加到 .cursor/mcp.json：

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

VS Code

将以下内容添加到 .vscode/mcp.json：

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

OpenCode

将以下内容添加到 opencode.json：

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

LibreChat

将以下内容添加到 librechat.yaml：

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

其他

任何支持 Streamable HTTP 和 OAuth 的 MCP 客户端都可以连接。请按以下方式配置：

• URL: https://mcp.clickhouse.cloud/clickstack

​

指定特定服务

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

​

开源和 BYOC

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

​

前置条件

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

Personal API Access Key 与 摄取 API key 不同；后者也可在 Team Settings 中找到，用于验证发送到 OpenTelemetry Collector 的遥测数据。

​

端点

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

本页中的示例使用前端应用 URL (默认端口为 8080) 。你也可以通过后端的 <BACKEND_URL>/mcp 直接访问 MCP 服务器，但并非所有部署都会暴露后端，因此本文档使用前端路径。

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

​

连接 MCP 客户端

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

Claude Code

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

Cursor

将以下内容添加到 .cursor/mcp.json：

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

VS Code

将以下内容添加到 .vscode/mcp.json：

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

OpenCode

将以下内容添加到 opencode.json：

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

LibreChat

将以下内容添加到 librechat.yaml：

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

其他

任何支持 Streamable HTTP 的 MCP 客户端都可以连接。按以下方式配置：

• URL： <YOUR_CLICKSTACK_URL>/api/mcp
• 请求头： Authorization: Bearer <YOUR_API_KEY>

​

你可以用 MCP 做什么？

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

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

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

​

多团队使用 (OSS/BYOC)

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

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

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

​

故障排查

​

ClickHouse Cloud 上的 ClickStack

OAuth 流程未完成

• 确认您的 MCP 客户端 支持 OAuth 2.0。仅支持 Bearer 令牌或 stdio 传输的客户端无法通过 Cloud 端点进行身份验证。
• 检查您的浏览器是否拦截了 OAuth 弹窗或重定向。
• 确认您的 ClickHouse Cloud 账户有权访问相应的 organization 和 服务。

MCP 已启用，但客户端无法连接

• 确认您使用的是 ClickStack 端点 (https://mcp.clickhouse.cloud/clickstack) ，而不是通用的 Cloud MCP 端点 (https://mcp.clickhouse.cloud/mcp) 。
• 确认该 服务 已在 Cloud 控制台 中启用 MCP。

请求发送到了错误的 服务

如果未提供 x-service-id 请求头，请求默认会发送到您账户中预配并使用的第一个 ClickStack 服务。传递该请求头即可指定特定的目标 服务。请参见指定特定 服务。

​

开源和 BYOC

我遇到了 403 身份验证错误

• 请确认你使用的是 Personal API Access Key (而不是摄取 API key) 。
• 确认该密钥已作为 Bearer 令牌包含在 Authorization 请求头中。
• 检查你的 ClickStack 实例是否正在运行，并且可通过你配置的 URL 访问。

我受到了速率限制

MCP 服务器 对每位用户实施 每分钟 600 次请求 的速率限制。如果超过此限制，请求会被暂时拒绝。请降低请求频率，或等待后再重试。

使用 x-hdx-team 请求头时出现 401 错误

请确认团队 ID 正确，并且你的用户账户属于该团队。

我无法连接到 MCP 服务器

• 确保你的 MCP 客户端 支持 Streamable HTTP 传输。仅支持 stdio 传输的旧版客户端将无法使用。
• 如果你在本地运行 ClickStack，请确认应用可通过已配置的 URL 访问 (默认为 http://localhost:8080) 。
• 对于位于负载均衡器或反向代理之后的 BYOC 部署，请确保 /api/mcp 路径未被拦截或重写。