MCP 工具清单¶

本文档介绍 OWL MCP Server 当前可通过 MCP 调用的业务工具能力，包括工具分类、权限类型、使用约定、工具总览，以及典型 MCP 使用路径。

工具可见范围和调用结果取决于当前接入使用的 API Key 权限。若 API Key 没有相关资源或操作权限，对应工具调用可能会失败，或返回空结果。

工具范围¶

OWL MCP Server 可执行的业务工具会随平台能力持续更新。实际可执行工具以 list_catalogs 和 list_tools 返回的工具目录为准。

当前文档覆盖以下业务分类：

权限类型¶

使用约定¶

facade 模式下，MCP 客户端应按以下顺序调用：

1. 调用 list_catalogs 查看可用分类。
2. 调用 list_tools，传入 catalog_id，查看该分类下的业务工具和参数。
3. 调用 exec_tool，传入 tool_name 和 parameters 执行业务工具。

static 模式下，客户端可以直接调用 tools/list 返回的业务工具，无需经过三个包装工具。无论使用哪种模式，工具参数和权限要求保持一致。

工具总览¶

Account¶

同组织发现使用下表工具。得到的 workspace_uuid 可作为 owl.data.same_org.trace.query 的 workspace_uuids 入参，用于跨工作空间 Trace 查询。

注意：返回结果中的 workspace_uuid 才是后续 workspace_uuids 入参；workspace_id 只用于列表分页，不要传给 Trace 查询工具。

Catalog¶

用于统一资源目录的实体类型发现、实体查询、实体详情获取和拓扑关系查询。

注意：仪表板工具（owl.dashboard.create / owl.dashboard.replace / owl.dashboard.get）仅在 OWL CLI 中提供，不会出现在 MCP 工具列表中，相关用法请参见 OWL CLI 文档。

Data¶

授权查询空间通过 owl.workspace.data_authorized.list 发现，支持 region_code、search、page_index、page_size，各站点独立分页。将 workspace_uuid 和 region_code 传给 owl.data.simple_query 的 workspace_uuids 和 target_region，即可查询同一目标站点内的多个授权空间。详见跨空间查询说明。

用于 DQL namespace 探查、数据源和字段发现、日志索引发现、SLO 查询、日志聚类分析、同组织跨工作空间 Trace 查询，以及面向 MCP 客户端的简化数据查询。当前 MCP 侧提供的是简化查询和查询辅助工具，不包含完整 DQL 或 PromQL 自定义执行工具。

owl.data.same_org.trace.query 的 workspace_uuids 省略或传空数组时只查询当前工作空间。同组织跨工作空间查询功能关闭时，只允许查询当前工作空间；传入其他工作空间 UUID 会返回参数错误。

Errors¶

用于错误中心的问题列表查询，以及评论的新增、查询和更新。

Event¶

用于事件中心列表查询和事件详情获取。

• owl.event.list 必须提供 start_time 和 end_time；status 可选值为 fatal、critical、error、warning 和 nodata，limit 默认值为 20、最大值为 100；返回项可能包含事件维度标签字段 df_dimension_tags。
• owl.event.get 的 timeRange 为可选的二元素数组 [start, end]，元素均为 13 位毫秒时间戳，且 end 必须大于 start。参数名为 timeRange，不要改写为 time_range。

Incident¶

owl.incident.get 接受故障 UUID（incident_*），返回详情及 related_event_refs。关联引用每页默认及上限 100，按 page_info.has_more 和 next_page_index 读取后续页，再根据事件引用调用 owl.event.get；不要将故障 UUID 当作事件文档 ID。引用总数与故障报告的事件总数可能不同，应保留并说明缺失的证据。

用于故障列表与详情、关联事件引用、故障评论、操作记录和值班排班查询。

Infrastructure¶

用于基础设施对象列表和详情查询，覆盖主机、容器、进程等资源对象。

LLM¶

用于 LLM 可观测应用列表查询。

Workspace¶

用于跨空间数据查询授权范围发现，以及当前空间成员列表查询和按姓名、邮箱关键字检索。

owl.member.list 保留为显式调用的兼容别名，不作为独立工具列出；CLI 需升级到支持别名的版本后执行 owl sync。

Monitor¶

用于监控器列表查询、详情获取、创建或更新，以及外部事件接收。

笔记¶

用于管理当前 API Key 账号可见的笔记。

• owl.nbook_note.list 的 page_index 默认值为 1，page_size 默认值为 20、最大值为 100。
• owl.nbook_note.get 是唯一返回 Markdown 正文 content 的笔记工具，但不返回 path、etag 或 version；list、add 和 modify 只返回摘要，不返回 content、path、ETag 或版本信息；delete 响应保持后端原有精简结构。
• type 支持 normal 和 runbook。owl.nbook_note.list 可按 type 过滤，省略时不过滤类型；owl.nbook_note.add 可设置 type，省略时后端创建 normal 笔记；get 和 modify 的响应会包含 type，但 get、modify、delete 都不接受 type 入参，已有笔记类型不可修改。
• owl.nbook_note.add 必须提供 title 和 content，不接受 path；created_source 固定由服务端设为 ai，创建账号取自当前 API Key。
• owl.nbook_note.modify 除 note_uuid 外，至少还要提供 title、content、tags 或 tag_kv 中的一项；省略 content 时保留原正文。
• 获取、修改和删除都使用列表返回的 note_uuid。不要传 path、etag、if_match、version、creator 或 created_source 等由后端管理的字段。
• tagkv_query 是列表工具使用的 TagKV 表达式字符串；tag_kv 是创建和修改工具使用的键值对象，两者不要混用。

Pipeline¶

用于 Pipeline 列表查询和样例验证。

mdsearch¶

用于检索统一文档语料、按 id 或 path 读取完整文档，以及浏览语料目录结构，支持中文、英文及混合查询。

MCP 使用路径¶

以下步骤以默认的 facade 模式为例。若服务端启用了 static 模式，可直接调用同名业务工具，无需经过 exec_tool。

数据查询类问题¶

适用于“查询指标、日志、RUM、APM、Network、Profile 数据”等问题。

1. 通过 exec_tool 调用 owl.data.show_dql_namespace 确认数据 namespace。
2. 根据数据域通过 exec_tool 调用发现类工具：
3. 指标：owl.metric.list
4. RUM：owl.rum.list
5. APM：owl.apm.list
6. Network：owl.network.list
7. Profile：owl.profile.list
8. 日志：owl.logging.list
9. 云账单：owl.billing.list
10. 日志索引：owl.log_index.list
11. 字段目录：owl.field_schema.get
12. 获取必要的 source、field、index 后，通过 exec_tool 调用 owl.data.simple_query 执行查询。

故障排查类问题¶

适用于“查询故障、追踪故障处理过程、补充故障评论”等问题。

1. 已知故障 UUID 时，通过 exec_tool 调用 owl.incident.get；目标未确定时先调用 owl.incident.list。
2. 按返回的分页信息读取全部关联事件引用，再调用 owl.event.get 获取事件内容。
3. 使用 owl.incident_comment.list 查看评论、owl.incident_operation.list 查看操作记录。
4. 需要补充处理信息时，通过 exec_tool 调用 owl.incident_comment.add。

资源对象定位类问题¶

适用于“查询主机、容器、进程等基础设施对象详情”的问题。

1. 通过 exec_tool 调用 owl.infrastructure.list 查找目标对象。
2. 根据返回结果中的标识信息，通过 exec_tool 调用 owl.infrastructure.get 获取对象详情。

跨工作空间 Trace 查询类问题¶

适用于“按 trace_id 查询一条跨同组织多个工作空间的 Trace”的问题。

1. 本空间 Trace 直接查询；需要其他同组织空间且 UUID 未确定时，通过 exec_tool 调用 owl.account.workspace.same_org.list 发现候选空间。
2. 从返回结果中取 workspace_uuid（不要取 workspace_id）。
3. 通过 exec_tool 调用 owl.data.same_org.trace.query，传入必填的 trace_id，并将所选 workspace_uuid 作为 workspace_uuids；省略或传空数组时只查询当前工作空间。
4. 如需附加过滤，使用不含外层花括号的 where_clause，且不要重复添加 trace_id 条件。跨工作空间 Trace 查询不要回退到 owl.data.simple_query。

笔记管理类问题¶

适用于“搜索、读取、创建、修改或删除笔记”等问题。

1. 通过 exec_tool 调用 owl.nbook_note.list 搜索笔记并取得 note_uuid。
2. 需要读取 Markdown 正文时，调用 owl.nbook_note.get。
3. 创建笔记时调用 owl.nbook_note.add，更新时调用 owl.nbook_note.modify。
4. 删除时调用 owl.nbook_note.delete；add、modify 和 delete 属于写入工具，执行前应由客户端进行人工确认。

监控器管理类问题¶

适用于“查询监控器、创建或更新监控器、发送外部事件”等问题。

1. 通过 exec_tool 调用 owl.monitor.list 查询监控器。
2. 根据返回结果中的 rule_uuid，通过 exec_tool 调用 owl.monitor.get 查看监控器详情。
3. 如需创建或更新监控器，通过 exec_tool 调用 owl.monitor.upsert。
4. 如需发送外部事件，通过 exec_tool 调用 owl.monitor.receive。