MCP Server¶

什么是 MCP Server？¶

MCP Server，模型上下文协议（Model Context Protocol，简称 MCP）是一个开放协议，旨在标准化应用程序与 AI 模型之间的安全连接和数据源访问。它的核心目标是让开发者能够通过统一的“工具”和“资源”，轻松地为模型提供上下文信息（如数据、内容、操作），从而增强模型能力，而无需重新训练模型。

基于 MCP Server 构建的服务，最终提供一个统一的多模型可调用接口。该服务支持多客户端接入，并采用 API Key 鉴权机制，以此安全访问观测云的各项核心功能，包括监控器、日志、仪表板及 DQL 查询。

使用准备¶

在接入 Owl MCP 服务前，建议完成以下准备工作：

创建具备对应业务权限的观测云 API Key
根据工作空间所在站点选择正确的 MCP Endpoint
在支持 MCP 的客户端中完成 Owl MCP 服务连接配置
根据实际使用目标准备查询时间范围、对象标识、仪表板 UUID、监控器 UUID、Incident UUID 等关键输入

使用约定¶

时间范围类工具统一使用 13 位毫秒时间戳
分页类工具普遍支持 page_size 和 page_index，默认值通常分别为 20 和 1
详情类工具通常依赖列表类工具返回的标识字段，例如 dashboard_uuid、rule_uuid、incident_uuid、issue_id
数据查询类工具建议按“先发现、后查询”的顺序使用：先通过 discovery 或索引类工具拿到可用取值，再执行正式查询
本文聚焦业务工具，不展开介绍 MCP 协议层的通用发现与执行接口

Endpoint¶

Owl MCP 服务按站点提供独立 Endpoint。请根据工作空间所在节点选择对应的服务地址。

支持 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`
私有部署版	私有部署版	以实际部署提供的 Owl MCP Endpoint 为准

Endpoint 规则与观测云 Open API 节点保持一致。对于 SaaS 站点，Owl MCP 地址基于对应站点域名生成，并统一以 /mcp 作为服务路径。

接入示例¶

此处以通过 Cherry Studio 接入方式为例。

接入方式

其他更多接入方式正在开发中，敬请期待！

下载版本¶

下载 MCP Server 客⼾端 Cherry Studio，选择对应版本；
打开 Cherry Studio，开始配置大模型基础服务。

此处以火山引擎为例，配置 API 密钥。

配置观测云 MCP 服务¶

⾃定义输入服务名称和描述；
类型选择 streamableHttp；
定义 URL：https://owl-mcp.guance.com/mcp；
请求头格式为：Authorization=DF-API-KEY；
配置完 MCP 服务后保存后开启，再回到⾸⻚，选择 MCP 服务。

配置说明¶

接⼝以 API KEY 为认证⽅式，每⼀次请求使⽤请求体 Header 中的 DF-API-KEY 的值作为有效性检验，以及本次请求的⼯作空间限定依据（取此 DF-API-KEY 所属的⼯作空间）；
当前 MCP 服务所展⽰的所有接⼝都只需要提供 API KEY（Header：DF-API-KEY）作为凭证。如果凭据存在且有效，则视为认证通过。

工具总览¶

当前共提供 37 个业务工具，覆盖 Dashboard、Data、Errors、Event、Field Schema、Incident、Infrastructure、LLM、Log Index、Member、Metric、Monitor、Pipeline、APM、RUM、Network、Profile、Catalog 等领域。

Dashboard¶

owl.dashboard.create¶

工具集：dashboard

功能：创建仪表板

参数：

name（必填，string）：仪表板名称
dashboard_json（必填，object）：仪表板模板内容，至少包含 title 和 main.charts

可提问示例：

帮我创建一个名为 “APM Overview” 的仪表板，标题同名，先放空图表
按我提供的 dashboard_json 新建一个 Nginx 监控仪表板

owl.dashboard.replace¶

工具集：dashboard

功能：替换已有仪表板内容

参数：

dashboard_uuid（必填，string）：目标仪表板 UUID
dashboard_json（必填，object）：新的仪表板模板内容

可提问示例：

把 dsbd_xxx 这个仪表板替换成我给你的新版配置
更新指定仪表板的标题和图表布局，使用这份 dashboard_json

owl.dashboard.get¶

工具集：dashboard

功能：获取仪表板详情

参数：

dashboard_uuid（必填，string）：仪表板 UUID

可提问示例：

查询仪表板 dsbd_xxx 的详细内容
把这个 dashboard UUID 对应的配置完整取出来

Data¶

owl.data.show_dql_namespace¶

工具集：data

功能：查看当前支持的 DQL namespace，以及各 namespace 是否支持 index 参数

参数：

无

可提问示例：

列出当前支持的 DQL namespace
哪些数据 namespace 支持传 index？

owl.data.query¶

工具集：data

功能：执行 Guance 的 DQL 或 PromQL 查询，适用于日志、指标、RUM、APM、Network、Profile 等数据域。若不确定 dql_namespace，应先调用 owl.data.show_dql_namespace。需要完整表达能力时优先使用 query_text，因为它适合直接写官方 DQL 语法，例如过滤、时间窗口、BY 分组、HAVING、ORDER BY、别名和聚合函数。注意 DQL 分组语法是 BY ...，不是 SQL 风格的 GROUP BY

参数：

dql_namespace（必填，string）：查询命名空间，常见如 L（日志）、M（指标）
start_time（必填，int）：开始时间，13 位毫秒时间戳
end_time（必填，int）：结束时间，13 位毫秒时间戳
query_mode（可选，string）：查询模式，支持 dql 或 promql，其中 promql 只适用于指标类查询
query_text（可选，string）：完整查询语句。写 DQL 时请按官方语法书写，例如 L::nginx:(count(*)) [1h] BY source, status，不要写 GROUP BY
source（可选，string）：未传 query_text 时用于拼接简单查询的数据源名
select（可选，string[]）：未传 query_text 时用于拼接简单查询的 select 表达式列表
index（可选，string）：日志 namespace 使用的索引名，对应 DQL 中的 namespace[index]。

推荐写法：

简单查询优先用 source + select
需要 WHERE、BY、HAVING、ORDER BY、复杂函数、别名或更完整语义时优先用 query_text
日志统计不要写 COUNT(L::*) GROUP BY ...，应写成 L::source:(count(*)) ... BY ... 这样的 DQL 形式

可提问示例：

查询最近 1 小时 Nginx 日志中的 500 错误
用 PromQL 查询最近 30 分钟 CPU 使用率趋势
在日志 namespace 下查询 default 索引里 nginx source 的明细数据
统计最近 1 小时 nginx 日志按 source 和 status 分组的数量

Errors¶

owl.errors.list¶

工具集：errors

功能：查询错误中心列表

参数：

start_time（必填，int）：开始时间，13 位毫秒时间戳
end_time（必填，int）：结束时间，13 位毫秒时间戳
page_size（可选，int）：每页数量
page_index（可选，int）：页码
conditions（可选，string）：过滤表达式
assigner（可选，string）：处理人过滤条件
issue_status（可选，string）：错误状态过滤条件

可提问示例：

查询最近 24 小时的错误中心列表
查一下当前分配给 Alice 的高优先级错误问题
按条件筛选最近一周的 Java 异常问题。

owl.errors.comment.add¶

工具集：errors

功能：为错误问题新增评论

参数：

issue_id（必填，string）：错误问题 ID
comment（必填，string）：评论内容
attachment_uuids（可选，string[]）：附件 UUID 列表
extend（可选，object）：扩展字段

可提问示例：

给 issue_xxx 添加评论：请先检查最近一次发布
在这个错误问题下追加一条处理说明，并带上附件 ID 列表。

owl.errors.comment.list¶

工具集：errors

功能：查询错误问题的评论列表

参数：

issue_id（必填，string）：错误问题 ID
page_size（可选，int）：每页数量
page_index（可选，int）：页码

可提问示例：

列出 issue_xxx 的全部评论
查看这个错误问题最近一页评论记录

owl.errors.comment.update¶

工具集：errors

功能：更新已有错误评论

参数：

comment_uuid（必填，string）：评论 UUID
comment（必填，string）：更新后的评论内容
attachment_uuids（可选，string[]）：附件 UUID 列表
extend（可选，object）：扩展字段

可提问示例：

把评论 comment_xxx 更新为“已确认根因，正在修复”
更新这条错误评论的正文，并补充附件列表

Event¶

owl.event.list¶

工具集：event

功能：查询事件列表

参数：

start_time（必填，int）：开始时间，13 位毫秒时间戳
end_time（必填，int）：结束时间，13 位毫秒时间戳
status（可选，string）：事件状态
limit（可选，int）：返回条数上限，最大 100

可提问示例：

查询最近 6 小时的事件列表
列出最近一天状态为告警中的事件，最多返回 50 条

owl.event.get¶

工具集：event

功能：获取事件详情

参数：

doc_id（必填，string）：事件文档 ID

可提问示例：

查看事件 doc_xxx 的详细信息
把这个事件 ID 对应的原始事件内容完整展示出来

Field Schema¶

owl.field_schema.get¶

工具集：field_schema

功能：获取字段目录简表，适合在构造查询条件、选择字段前先查看可用字段

参数：

无

可提问示例：

列出当前可用的字段目录
我想写数据查询，先把字段清单给我看一下

Incident¶

owl.incident.list¶

工具集：incident

功能：查询 Incident 列表

参数：

search（可选，string）：关键字搜索
page_size（可选，int）：每页数量
page_index（可选，int）：页码

可提问示例：

查询当前 Incident 列表
搜索名称里包含“Redis”的 Incident

Incident Comment¶

owl.incident_comment.list¶

工具集：incident_comment

功能：查询指定 Incident 的评论列表

参数：

incident_uuid（必填，string）：Incident UUID

可提问示例：

查看 Incident inc_xxx 的评论列表
把这个 Incident 下的所有评论按时间列出来

owl.incident_comment.add¶

工具集：incident_comment

功能：为指定 Incident 新增评论

参数：

incident_uuid（必填，string）：Incident UUID
comment（必填，string）：评论内容

可提问示例：

给 inc_xxx 添加评论：正在联系值班同学处理
在这个 Incident 下追加一条最新进展说明

Incident Operation¶

owl.incident_operation.list¶

工具集：incident_operation

功能：查询 Incident 操作记录

参数：

incident_uuid（必填，string）：Incident UUID
page_size（可选，int）：每页数量
page_index（可选，int）：页码

可提问示例：

查看 inc_xxx 的操作记录
把这个 Incident 最近两页操作历史列出来

Incident Schedule¶

owl.incident_schedule.list¶

工具集：incident_schedule

功能：查询 Incident 排班列表

参数：

search（可选，string）：排班名称关键字
page_size（可选，int）：每页数量
page_index（可选，int）：页码

可提问示例：

列出当前所有 Incident 排班
搜索名称里包含“SRE”的排班表

owl.incident_schedule.get¶

工具集：incident_schedule

功能：获取 Incident 排班详情

参数：

schedule_uuid（必填，string）：排班 UUID

可提问示例：

查看排班 schedule_xxx 的详细配置
把这个值班排班的时区、时间段和通知目标展示出来

Infrastructure¶

owl.infrastructure.list¶

工具集：infrastructure

功能：查询基础设施对象列表，支持主机、容器、进程三类资源

参数：

resource_type（必填，string）：资源类型，支持 host、container、process
limit（可选，int）：返回条数上限，最大 100
filters（可选，object[]）：过滤条件列表。每项包含 field、op、value

可提问示例：

列出最近可见的主机对象
查询名称里包含 prod 的容器，最多返回 20 条
按字段条件筛选进程对象列表

owl.infrastructure.get¶

工具集：infrastructure

功能：获取单个基础设施对象详情

参数：

resource_type（必填，string）：资源类型，支持 host、container、process
identity_value（必填，string）：对象标识值

可提问示例：

查看主机 host-01 的详细信息
获取容器 container_xxx 的完整对象详情

LLM¶

owl.llm.list¶

工具集：llm

功能：查询 LLM 应用列表

参数：

search（可选，string）：关键字搜索
type（可选，string）：应用类型过滤
page_size（可选，int）：每页数量
page_index（可选，int）：页码

可提问示例：

列出当前所有 LLM 应用
搜索名称里包含“chat”的 LLM 应用
按类型筛选并返回第一页应用列表

Log Index¶

owl.log_index.list¶

工具集：log_index

功能：查询日志索引列表，适合在日志查询前先确定可用索引

参数：

无

可提问示例：

列出当前所有日志索引
我准备查日志，先给我看一下可用的 index

owl.log_index.get¶

工具集：log_index

功能：获取日志索引详情

参数：

index_uuid（必填，string）：日志索引 UUID

可提问示例：

查看日志索引 index_xxx 的详细配置
把这个 index UUID 对应的索引详情展示出来

Member¶

owl.member.list¶

工具集：member

功能：查询成员列表

参数：

search（可选，string）：成员姓名或邮箱关键字

可提问示例：

列出当前工作空间所有成员
搜索邮箱里包含 alice 的成员

Metric¶

owl.metric.list¶

工具集：metric

功能：查询指标域的 source 或 field 发现结果，用于后续数据查询

参数：

mode（可选，string）：source 或 field，默认 source

可提问示例：

列出当前可用的 metric source
查看指标域有哪些 field 可以用于查询

Monitor¶

owl.monitor.list¶

工具集：monitor

功能：查询监控器列表

参数：

search（可选，string）：监控器名称关键字
status_list（可选，int[]）：状态列表，支持 0、2

可提问示例：

列出当前所有监控器
查询名称里包含“CPU”的启用中监控器

owl.monitor.get¶

工具集：monitor

功能：获取监控器详情

参数：

rule_uuid（必填，string）：监控器规则 UUID

可提问示例：

查看监控器 rul_xxx 的详细配置
把这个 monitor rule 的完整定义取出来

owl.monitor.upsert¶

工具集：monitor

功能：创建监控器，或在传入 rule_uuid 时更新已有监控器

参数：

json_script（必填，object）：监控器配置对象
rule_uuid（可选，string）：已有监控器规则 UUID，传入后执行更新
status（可选，int）：监控器状态，支持 0、2
secret（可选，string）：当 json_script.type 为 OuterEventChecker 时使用
alert_policy_uuids（可选，string[]）：告警策略 UUID 列表
extend（可选，object）：扩展字段
tags（可选，array）：标签列表

可提问示例：

创建一个 CPU 使用率过高的监控器
更新 rul_xxx 这个监控器的标题和告警消息
创建一个 OuterEventChecker 类型的监控器并绑定指定告警策略

owl.monitor.receive¶

工具集：monitor

功能：接收外部事件。支持直接投递到已有 target，也支持先创建一个 OuterEventChecker 再投递事件

参数：

event（必填，object）：事件对象，必须包含 status、title、message、dimension_tags、check_value
target（可选，object）：已有事件接收目标，包含 secret、sub_uri
monitor（可选，object）：用于创建接收目标的监控器配置，包含 secret、sub_uri、status、title、message_template、alert_policy_uuids
extra_data（可选，object）：附加数据

可提问示例：

把这条外部告警事件发送到指定 target
先创建一个事件接收监控器，再把 CPU 告警事件推送进去
用现有 secret 和 sub_uri 上报一条 critical 事件

Network¶

owl.network.list¶

工具集：network

功能：查询网络域的 source 或 field 发现结果，用于后续数据查询

参数：

mode（可选，string）：source 或 field，默认 source

可提问示例：

列出当前可用的 network source
查看网络域有哪些 field 可以直接查询

Pipeline¶

owl.pipeline.list¶

工具集：pipeline

功能：查询 Pipeline 列表，并返回可直接阅读的 Pipeline 内容

参数：

search（可选，string）：Pipeline 名称关键字
scope（可选，string）：Pipeline 作用域
categories（可选，string[]）：分类过滤列表

可提问示例：

列出当前所有 Pipeline
搜索名称里包含 nginx 的 Pipeline
查询 local 作用域下指定分类的 Pipeline

owl.pipeline.validate¶

工具集：pipeline

功能：校验 Pipeline。当前调用返回固定结果 DEFERRED_TOOL

参数：

无

可提问示例：

校验一条 Pipeline 规则
尝试执行 Pipeline 校验工具

Profile¶

owl.profile.list¶

工具集：profile

功能：查询性能剖析域的 source 或 field 发现结果，用于后续数据查询

参数：

mode（可选，string）：source 或 field，默认 source

可提问示例：

列出当前可用的 profile source
查看 profile 域有哪些 field

RUM¶

owl.rum.list¶

工具集：rum

功能：查询 RUM 域的 source 或 field 发现结果，用于后续数据查询

参数：

mode（可选，string）：source 或 field，默认 source

可提问示例：

列出当前可用的 RUM source
查看 RUM 域有哪些 field

APM¶

owl.apm.list¶

工具集：apm

功能：查询 APM 域的 source 或 field 发现结果，用于后续数据查询

参数：

mode（可选，string）：source 或 field，默认 source

可提问示例：

列出当前可用的 APM source
查看 APM 域有哪些 field

Catalog¶

owl.catalog.query¶

工具集：catalog

功能：查询 Catalog。当前调用返回固定结果 DEFERRED_TOOL

参数：

无

可提问示例：

查询 Catalog 内容
尝试执行 Catalog 查询工具

owl.catalog.update¶

工具集：catalog

功能：更新 Catalog。当前调用返回固定结果 DEFERRED_TOOL

参数：

无

可提问示例：

更新 Catalog 中某个对象
尝试执行 Catalog 更新工具。

典型使用路径¶

数据分析类问题¶

先调用 owl.data.show_dql_namespace 确认 namespace
按需要调用 owl.metric.list、owl.rum.list、owl.apm.list、owl.network.list、owl.profile.list、owl.log_index.list、owl.field_schema.get 获取查询所需的 source、field、index
最后调用 owl.data.query 执行正式查询

告警与故障处理类问题¶

使用 owl.monitor.list、owl.monitor.get 查看监控器
使用 owl.event.list、owl.event.get 查看事件
使用 owl.incident.list、owl.incident_comment.list、owl.incident_operation.list 查看 Incident 进展
使用 owl.errors.list 与评论工具跟踪错误问题处理过程

配置管理类问题¶

使用 owl.dashboard.create、owl.dashboard.replace、owl.dashboard.get 管理仪表板
使用 owl.pipeline.list 查看 Pipeline
使用 owl.monitor.upsert 创建或更新监控器

MCP Server¶

什么是 MCP Server？¶

使用准备¶

使用约定¶

Endpoint¶

支持 Endpoint¶

接入示例¶

下载版本¶

配置观测云 MCP 服务¶

配置说明¶

工具总览¶

Dashboard¶

owl.dashboard.create¶

owl.dashboard.replace¶

owl.dashboard.get¶

Data¶

owl.data.show_dql_namespace¶

owl.data.query¶

Errors¶

owl.errors.list¶

owl.errors.comment.add¶

owl.errors.comment.list¶

owl.errors.comment.update¶

Event¶

owl.event.list¶

owl.event.get¶

Field Schema¶

owl.field_schema.get¶

Incident¶

owl.incident.list¶

Incident Comment¶

owl.incident_comment.list¶

owl.incident_comment.add¶

Incident Operation¶

owl.incident_operation.list¶

Incident Schedule¶

owl.incident_schedule.list¶

owl.incident_schedule.get¶

Infrastructure¶

owl.infrastructure.list¶

owl.infrastructure.get¶

LLM¶

owl.llm.list¶

Log Index¶

owl.log_index.list¶

owl.log_index.get¶

Member¶

owl.member.list¶

Metric¶

owl.metric.list¶

Monitor¶

owl.monitor.list¶

owl.monitor.get¶

owl.monitor.upsert¶

owl.monitor.receive¶

Network¶

owl.network.list¶

Pipeline¶

owl.pipeline.list¶

owl.pipeline.validate¶

Profile¶

owl.profile.list¶

RUM¶

owl.rum.list¶

APM¶

owl.apm.list¶

Catalog¶

owl.catalog.query¶

owl.catalog.update¶

典型使用路径¶

数据分析类问题¶

告警与故障处理类问题¶

配置管理类问题¶

文档内容是否对您有帮助？ ×