> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStack MCP 服务器

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

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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

这样一来，你就可以使用 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Cursor](https://www.cursor.com/) 或任何兼容 MCP 的客户端，在不离开开发环境的情况下排查故障、构建仪表盘并管理你的可观测性配置。

<div id="availability">
  ## 可用性
</div>

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

| 部署                                                | 状态   |
| ------------------------------------------------- | ---- |
| **开源 ClickStack**                                 | 可用   |
| **BYOC (自备 Cloud)**                               | 可用   |
| **托管 ClickStack**                                 | 即将推出 |
| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | 不支持  |

<Info>
  **托管 ClickStack**

  托管 ClickStack 对 MCP 服务器的支持正在积极开发中，很快即可提供。本页中的说明适用于开源和 BYOC 部署。
</Info>

<div id="prerequisites">
  ## 前置条件
</div>

在连接 MCP 客户端 之前，您需要：

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/vQMVv9Ng6hRPWQ0d/images/clickstack/api-key-personal.png?fit=max&auto=format&n=vQMVv9Ng6hRPWQ0d&q=85&s=00e36c597b480e04b36ad301640f1537" alt="Team Settings 中的 Personal API Access Key" size="md" border width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

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

<div id="endpoint">
  ## 端点
</div>

可通过 ClickStack 前端 URL 上的 `/api/mcp` 路径访问 MCP 服务器：

例如，使用默认本地部署时：

如果你修改了默认设置，请将 `localhost:8080` 替换为你的实例主机和端口。

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

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

<div id="connecting-a-client">
  ## 连接 MCP 客户端
</div>

下面的示例说明了如何配置常用的 MCP 客户端。请将 `<YOUR_CLICKSTACK_URL>` 替换为你的实例 URL (例如 `http://localhost:8080`) ，并将 `<YOUR_API_KEY>` 替换为你的 Personal API Access Key。

<div id="claude-code">
  ### Claude Code
</div>

```shell theme={null}
claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

<div id="cursor">
  ### Cursor
</div>

将以下内容添加到项目的 `.cursor/mcp.json` 文件中，或添加到全局 Cursor 设置中：

```json theme={null}
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="opencode">
  ### OpenCode
</div>

将以下内容添加到 `opencode.json` 配置文件中：

```json theme={null}
{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="other-clients">
  ### 其他客户端
</div>

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

* **URL:** `<YOUR_CLICKSTACK_URL>/api/mcp`
* **请求头:** `Authorization: Bearer <YOUR_API_KEY>`

<div id="capabilities">
  ## 你可以用 MCP 做什么？
</div>

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

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

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

<div id="multi-team">
  ## 多团队使用
</div>

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

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

<div id="troubleshooting">
  ## 故障排查
</div>

<Accordion title="我遇到了 403 身份验证错误">
  * 请确认你使用的是 **Personal API Access Key** (而不是摄取 API key) 。
  * 确认该密钥已作为 `Bearer` 令牌包含在 `Authorization` 请求头中。
  * 检查你的 ClickStack 实例是否正在运行，并且可通过你配置的 URL 访问。
</Accordion>

<Accordion title="我受到了速率限制">
  MCP 服务器 对每位用户实施 **每分钟 600 次请求** 的速率限制。如果超过此限制，请求将被暂时拒绝。请降低请求频率，或等待后再重试。
</Accordion>

<Accordion title="使用 x-hdx-team 请求头时出现 401 错误">
  请确认团队 ID 正确，并且你的用户账户属于该团队。
</Accordion>

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