MCP Server 快速开始¶

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

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

使用前准备¶

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

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

Endpoint¶

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

部署类型	站点名	Endpoint
SaaS 部署	中国区1（杭州）	`https://owl-mcp.guance.com/mcp`
SaaS 部署	中国区2（宁夏）	`https://aws-owl-mcp.guance.com/mcp`
SaaS 部署	中国区4（广州）	`https://cn4-owl-mcp.guance.com/mcp`
SaaS 部署	中国区6（香港）	`https://cn6-owl-mcp.guance.one/mcp`
SaaS 部署	海外区1（俄勒冈）	`https://us1-owl-mcp.guance.com/mcp`
SaaS 部署	欧洲区1（法兰克福）	`https://eu1-owl-mcp.guance.one/mcp`
SaaS 部署	亚太区1（新加坡）	`https://ap1-owl-mcp.guance.one/mcp`
SaaS 部署	非洲区1（南非）	`https://za1-owl-mcp.guance.com/mcp`
SaaS 部署	印尼区1（雅加达）	`https://id1-owl-mcp.guance.com/mcp`
SaaS 部署	中东区1（阿联酋）	`https://me1-owl-mcp.guance.com/mcp`
SaaS 部署	免费专区（北京）	`https://cn3-owl-api.guance.com`
私有部署版	私有部署版	以实际部署提供的 Owl MCP Endpoint 为准

鉴权方式¶

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

Authorization: Bearer <API Key>

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

客户端配置¶

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 时，建议遵循以下约定：

类型	约定
时间范围类工具	统一使用 13 位毫秒时间戳
分页类工具	通常支持 `page_size` 和 `page_index`
详情类工具	通常依赖列表类工具返回的标识字段，例如 `dashboard_uuid`、`rule_uuid`、`incident_uuid`、`issue_id`
数据查询类工具	建议按“先发现、后查询”的顺序使用，先通过发现类工具获取可用 `source`、`field`、`index`，再执行正式查询

验证方式¶

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

列出当前可用的指标 source。

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