OneUptime MCP Server 实战手册：三分钟接入 AI 监控助手，155 个工具避坑指南

OneUptime MCP Server 实战手册三分钟接入 AI 监控助手155 个工具避坑指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime凌晨三点告警响了你想让 AI 助手帮你查结果它既看不到你的监控器、事件也摸不到遥测数据——只能人肉翻面板。OneUptime 内置的 MCP 服务器MCPModel Context Protocol可以理解为 LLM 连接外部工具的USB 标准接口补上的正是这块一个/mcp端点把 Claude、VS Code Copilot、Cursor 这类客户端接到你的监控实例上约 155 个工具覆盖事件处置、状态页更新、遥测查询。这篇讲怎么配、怎么用、权限怎么收、出错怎么修。零安装跑通最小闭环MCP 服务器随 OneUptime 实例一起托管走 Streamable HTTP 传输本地什么都不用装。端点就一个云版是https://oneuptime.com/mcp自托管就是你的域名加/mcp由 App 容器在 Nginx 后面提供。最短路径是 Claude Desktop打开系统里的claude_desktop_config.jsonmacOS 在~/Library/Application Support/Claude/Windows 在%APPDATA%\Claude\Linux 在~/.config/Claude/追加一段{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp, headers: { x-api-key: 你的项目APIKey } } } }自托管用户把域名换掉即可。VS Code1.99和 Cursor 同理都是指向/mcp并带上x-api-key头VS Code 还能用password: true的输入变量在启动时提示输密钥避免明文写进配置文件。客户端重启后问一句我有哪些监控器能列出监控器就算通了。不经过客户端、只想确认服务活着的话你试试这样curl https://oneuptime.com/mcp/health预期看到status: healthy、mode: stateless和一个约 155 的tools计数。顺手curl https://你的域名.com/mcp/tools还能拿到全部工具的名称和描述不用翻文档。按场景用从巡检到公共信息日常巡检问而不是翻列出最近一小时状态为 down 的监控器、我有多少个活跃事件——这类话直接发给 AI它会自动调list_monitors、count_incidents这类工具。两个值得知道的默认值列表默认每页 10 条、上限 100 条响应会带hasMore并在还有下一页时提示你用skip继续翻get_/list_工具支持select字段选择JSON、HTML、超长文本这类重字段默认被排除要用得显式点名省得一次拉回一大坨。事件响应告警到解决一个循环这是收益最大的场景。工作流工具acknowledge_incident、resolve_incident、add_incident_note等让你不用了解 OneUptime 数据模型内部——比如解决事件在底层其实是写一条指向项目Resolved状态的IncidentStateTimeline记录工具帮你做了。add_incident_note还支持visibility: internal仅团队可见默认或public发布到状态页给客户看且支持 Markdown。一条典型处置循环你直接用自然语言驱动即可列出最近的事件 → 受理最严重的那个 → 查最近30分钟的日志和异常 → 发一条公开备注说明正在处理 → 恢复后标记解决OneUptime 内置的 AI 调查也是同一套工具思路的体现——代理边推理边查事件时间线、聚合指标、翻日志注意一点add_incident_note的公开备注会出现在你的状态页上措辞会被客户读到让 AI 写之前自己过一眼。公共状态页不拿密钥也能查只想暴露公共信息、不想给 AI 任何项目权限去掉配置里的headers直接连get_public_status_page_overview、get_public_status_page_incidents、get_public_status_page_scheduled_maintenance、get_public_status_page_announcements四个工具免鉴权接受状态页 UUID 或状态页域名。状态页所有者还能在 Status Page → Advanced Settings → MCP Server 单独关掉某个状态页的 MCP 访问默认开。关掉只影响这四个公共工具状态页网站、RSS 和公共 JSON API 都不受影响该项目自己的认证工具照常工作。查遥测时间过滤是硬要求日志、指标、span、异常、监控器日志只暴露list_和count_如list_logs、count_spans没有创建类工具——遥测走 OpenTelemetry 摄取本来就不该由 MCP 写。查询字段接受直接值或操作符对象操作符有EqualTo、NotEqual、IsNull、NotNull、EqualToOrNull、GreaterThan、LessThan、GreaterThanOrEqual、LessThanOrEqual、InBetween、Search、Includes排序值ASC/DESC{ query: { time: { _type: GreaterThan, value: 2026-09-24T00:00:00.000Z } }, sort: { time: DESC }, limit: 20 }这些操作符提示已经自动写进了 query 参数的描述里AI 客户端看得到。记住一条纪律遥测表很大务必按时间范围过滤、limit 保持 10–50不然全表扫描的代价最终是你的。认证与权限别把主密钥喂给 AI认证只认两个请求头x-api-key直接放密钥或Authorization: Bearer 你的密钥scheme 大小写不敏感。密钥是项目级的服务器从密钥反推项目所以所有 create 工具永远不需要projectId参数。 最关键的一条主masterAPI Key 也会被这个请求头接受但它给的是整个实例的管理员权限。AI 代理永远只配项目级密钥且按最小权限给——只读密钥就能覆盖全部get_/list_/count_工具完整的增删改查才需要项目管理员权限。工具注解readOnlyHint、destructiveHint只是建议不少客户端会无差别自动批准非只读调用。所以源码里留了两个服务端硬开关接受true/1/yesMCP_READ_ONLYtrue只暴露读工具MCP_ALLOW_DESTRUCTIVEfalse保留 create/update 但移除全部 delete 工具。给 AI 代理开的实例建议默认开前者。常见坑按症状→原因→解法看症状某工具报 403 或字段缺失换把密钥就好 → 原因受限密钥读不了默认全字段里的某列API 会直接拒绝整个请求 → 解法服务端已自动剔除该列重试最多 10 次你不用手动拼select仍失败就去核对密钥权限范围。症状401 一律被拒 → 原因密钥打错、多了空白字符或已过期 → 解法到 Project Settings → API Keys 重新复制一份整段粘贴。底层机制速览无状态为什么不会丢请求只讲三个你排障时会用到的设计决策。无状态像 drive-thru 窗口每单都从头开始不靠通话记录认人。每个 POST 都新建一个McpServer实例加 Streamable HTTP 传输处理完立刻销毁不签发、不保留任何会话 ID。这么设计是被逼的——早期实现用进程内 Map 存会话多副本部署时initialize落在 worker A、下一个请求被负载均衡到 worker B直接 404 MCP session not found。安全的原因是工具本身不携带会话状态tools/list来自启动时绑定的工具列表每次tools/call都用同一请求头里的密钥鉴权。细节见 无状态路由处理器。密钥用闭包绑定既然每个请求一个服务器实例registerToolHandlers()就把本次请求的apiKey闭包进工具处理器里而不是存进程级全局变量——否则并发请求会互相踩到别人的密钥。见 工具注册与执行。错误走带内结果失败不抛 MCP 协议错误而是返回isError: true的工具结果里面带statusCode、details和suggestion404 会建议你用 list 工具找 ID429 提示稍后重试。这样 AI 代理能读到失败原因并自我纠正而不是整个会话崩掉。协议版本与响应格式的协商也在请求进 SDK 前完成更新的客户端版本自动向下协商不兼容的版本返回 400 并列出支持列表见 传输协商 与 底层 API 服务。排错与自检端点方法行为/mcpPOSTJSON-RPC 请求工具调用等/mcpGET无 SSE 头返回 JSON 发现负载带 SSE 头返回 405/mcpDELETE空操作无状态没有会话可终止/mcp/health、/mcp/toolsGET健康检查 / 工具清单遇到 X → 大概率是 Y → 这样修400 且错误体列出支持的协议版本 → 客户端发的MCP-Protocol-Version太旧或格式不是YYYY-MM-DD→ 去掉该头让initialize握手自己协商或升级客户端比服务器新的版本会被自动协商到共同最高版本不用管。406 Not Acceptable → 你的Accept头只声明了该端点产不出来的类型 → 别手动设Accept客户端默认值json event-stream就是对的。404 MCP session not found → 实例还是旧版本或客户端带着旧会话的mcp-session-id头 → 升级实例新版服务器直接忽略这个头请求本身仍然有效。列表看起来没数据 → 不是丢了是默认每页 10 条且hasMore: true→ 按提示带skip续翻或把limit提到 100。最后留一个自检手段接入后、排障时都先跑它# 健康检查预期 healthy / stateless / tools 数量 curl https://你的域名.com/mcp/health # 工具清单确认工具面是否被 MCP_READ_ONLY 等开关裁剪 curl https://你的域名.com/mcp/tools延伸阅读MCP 模块 README 与全部源码入口工具生成与写入策略开关工作流工具定义官方英文文档原文下一步现在就去 Project Settings → API Keys把之前那个权限过大的密钥删掉新建一个只读的 MCP-readonly替换进客户端配置重跑一遍 Quick Start 里的巡检问句——还能列出监控器说明最小权限闭环成立断了就回来翻上面的排错清单。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考