MCP Server 快速开始¶

OWL MCP Server 是观测云基于 Model Context Protocol 提供的服务端实现。它将 观测云 的指标、日志、事件、监控器、APM、RUM、基础设施、笔记等能力封装为 MCP 工具，供支持 MCP 的 AI 客户端调用。

本文档说明如何通过 streamableHttp 接入 OWL MCP Server。

MCP 客户端可调用的代表性工具还包括：

• 同组织跨工作空间 Trace 查询：先通过 owl.account.workspace.same_org.list 发现候选工作空间，再将返回的 workspace_uuid 作为 workspace_uuids 传给 owl.data.same_org.trace.query；workspace_id 仅用于列表分页，不能用于查询。
• 笔记：owl.nbook_note.list / owl.nbook_note.get / owl.nbook_note.add / owl.nbook_note.modify / owl.nbook_note.delete，用于列出、读取、创建、修改和删除笔记；支持 normal 和 runbook 两种类型，list 可按 type 过滤，add 可设置 type；只有 get 返回 Markdown 正文，add、modify 和 delete 属于写入工具，建议在 MCP 客户端中配置人工确认。
• 事件查询：owl.event.list / owl.event.get，用于按时间范围和状态查询事件列表，以及根据事件文档 ID 获取详情。
• Pipeline 查询与样例验证：owl.pipeline.list / owl.pipeline.validate，用于查询 Pipeline，或使用样例数据验证处理结果；验证只执行测试，不会创建或修改 Pipeline。
• 简化数据查询：owl.data.simple_query，提供更易用的数据查询入口。
• 文档检索：mdsearch_search / mdsearch_document / mdsearch_catalog，用于检索观测云文档。
• SLO 列表：owl.slo.list，列出已配置的 SLO。

使用前准备¶

接入前请确认已完成以下准备：

1. 已创建具备对应业务权限的 观测云 API Key
2. 已获取工作空间所属站点对应的 OWL MCP Endpoint
3. MCP 客户端中已完成 OWL MCP 服务连接配置
4. 当前网络环境可以访问 OWL MCP Endpoint

Endpoint¶

OWL MCP Server 按站点提供独立 Endpoint。请根据工作空间所属站点选择对应地址。

鉴权方式¶

在 MCP 客户端中配置请求头：

Authorization: Bearer <API Key>

其中，<API Key> 为 观测云 API Key，请妥善保管，不要将其写入公开代码仓库、共享文档或长期日志中。

OWL MCP Server 会先完成鉴权再进入 MCP 处理。未认证或凭据无效的请求会被直接拒绝，返回 401 Unauthorized 并带响应头 WWW-Authenticate: Bearer realm="mcp"。此外，触发限流会返回 429，来源 IP 不在白名单会返回 403。

客户端配置¶

OWL MCP Server 使用标准 streamableHttp 接入方式，可接入支持该传输方式的 MCP 客户端。不同客户端的配置入口和字段名称可能略有差异，请以实际客户端文档为准。

以下仅以 Cherry Studio、OpenClaw 和 Hermes 为例，说明常见 MCP 客户端的配置方式。其他支持 streamableHttp 的 MCP 客户端，也可以按相同原则配置：

• URL 填写工作空间所属站点对应的 OWL MCP Endpoint
• 请求头中配置 Authorization: Bearer <API Key>
• 启用该 MCP 服务

以下示例使用占位地址 your-owl-mcp-endpoint。实际接入时，请替换为工作空间所属站点对应的 OWL MCP Endpoint。

Cherry Studio¶

在 Cherry Studio 中新增一个 MCP 服务，按以下方式配置：

• 类型：streamableHttp
• URL：your-owl-mcp-endpoint
• 请求头：Authorization=Bearer <API Key>

完成配置后保存并启用，再回到客户端首页选择该 MCP 服务。

OpenClaw¶

openclaw mcp set owl '{
  "type": "streamableHttp",
  "url": "your-owl-mcp-endpoint",
  "headers": {
    "Authorization": "Bearer <API Key>"
  },
  "enabled": true
}'

验证配置：

openclaw mcp list
openclaw mcp show owl

Hermes¶

编辑 ~/.hermes/config.yaml：

mcp_servers:
  owl:
    type: streamableHttp
    url: your-owl-mcp-endpoint
    headers:
      Authorization: Bearer <API Key>
    enabled: true

验证配置：

hermes mcp list
hermes mcp test owl

使用约定¶

使用 OWL MCP Server 时，建议遵循以下约定：

验证方式¶

配置完成后，可以在 MCP 客户端中提问：

列出当前可用的指标 source。

客户端应能发现 list_catalogs、list_tools、exec_tool，并可通过 exec_tool 调用 owl.metric.list。如果无法连接、认证失败、工具列表为空或返回结果为空，请查看 故障排查。