跳转到主要内容
ClickStack 内置了 Model Context Protocol (MCP) 服务器，让 AI 助手能够与你的可观测性数据交互。连接后，AI 助手可以通过自然语言查询日志、链路追踪和指标；管理仪表盘和告警；浏览数据源；以及使用已保存的搜索。 这样一来，你就可以使用 Claude Code、Cursor 或任何兼容 MCP 的客户端，在不离开开发环境的情况下排查故障、构建仪表盘并管理你的可观测性配置。

​
可用性

MCP 服务器可用于以下 ClickStack 部署类型：
部署状态
开源 ClickStack可用
BYOC (自备 Cloud)可用
托管 ClickStack即将推出
HyperDX v1 (hyperdx.io)不支持
托管 ClickStack托管 ClickStack 对 MCP 服务器的支持正在积极开发中，很快即可提供。本页中的说明适用于开源和 BYOC 部署。

​
前置条件

在连接 MCP 客户端 之前，您需要：
  • 一个正在运行的 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 服务器： 例如，使用默认本地部署时： 如果你修改了默认设置，请将 localhost:8080 替换为你的实例主机和端口。
本页中的示例使用前端应用 URL (默认端口为 8080) 。你也可以通过后端的 <BACKEND_URL>/mcp 直接访问 MCP 服务器，但并非所有部署都会暴露后端，因此本文档使用前端路径。
MCP 服务器 使用 Streamable HTTP 传输和 Bearer token 身份验证。

​
连接 MCP 客户端

下面的示例说明了如何配置常用的 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 文件中，或添加到全局 Cursor 设置中： 
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

​
OpenCode

将以下内容添加到 opencode.json 配置文件中： 
{
  "mcp": {
    "hyperdx": {
      "type": "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 客户端 会在连接时自动发现可用工具。

​
多团队使用

默认情况下，MCP 请求会在你的主团队上下文中处理。如果你属于多个团队，可以在传递 Authorization 请求头的同时，添加一个值为该团队 ID 的 x-hdx-team 请求头，以指定特定团队。如果省略该请求头，则会使用你的主团队。如果你指定了一个自己不属于的团队，请求会被拒绝，并返回 401 错误。 使用 MCP 客户端 中的团队列表工具，查看你可以访问哪些团队以及当前处于活动状态的是哪个团队。

​
故障排查

  • 请确认你使用的是 Personal API Access Key (而不是摄取 API key) 。
  • 确认该密钥已作为 Bearer 令牌包含在 Authorization 请求头中。
  • 检查你的 ClickStack 实例是否正在运行，并且可通过你配置的 URL 访问。
MCP 服务器 对每位用户实施 每分钟 600 次请求 的速率限制。如果超过此限制，请求将被暂时拒绝。请降低请求频率，或等待后再重试。
请确认团队 ID 正确，并且你的用户账户属于该团队。
  • 确保你的 MCP 客户端 支持 Streamable HTTP 传输。仅支持 stdio 传输的旧版客户端将无法使用。
  • 如果你在本地运行 ClickStack，请确认应用可通过已配置的 URL 访问 (默认为 http://localhost:8080) 。
  • 对于位于负载均衡器或反向代理之后的 BYOC 部署，请确保 /api/mcp 路径未被拦截或重写。
最后修改于 2026年6月10日