AI替你盯监控OneUptime MCP 服务器实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime凌晨三点告警轰炸而来值班人还没睁眼——AI 能不能先把事件受理掉、查完日志再补上公告OneUptime MCP 服务器就是为这一刻准备的它让 AI 助手直连你的监控基础设施用自然语言完成查询、创建、处置全程无需你碰控制台。工具总数约 155 个22 类资源的 CRUD 遥测查询 工作流工具资源类别监控、事件、告警、状态页、计划维护、团队与值班、标签、遥测传输协议Streamable HTTP可理解为基于 HTTP 的 JSON-RPC支持流式响应本地安装不需要服务器随你的 OneUptime 实例托管云版在https://oneuptime.com/mcp自托管在https://your-oneuptime-domain.com/mcp为什么需要它你有没有经历过这种循环故障发生你从监控平台切到告警群、再切到状态页、再切到值班表手动点一圈按钮才算响应完了。真正消耗时间的不是点击而是每次切换时丢失的上下文。MCPModel Context Protocol解决的就是上下文问题它给 LLM 定义了一套调用外部工具的标准接口AI 助手不再需要你复制粘贴监控数据而是直接调工具——查监控器、建事件、发公告一步到位。OneUptime 把这个 MCP 服务器直接内嵌在实例里意味着你不需要额外部署任何组件/mcp路由随平台一起上线。从踩坑角度看这套设计的价值在闭环过去 AI 只能帮你看监控数据现在它能替你把数据看完、把动作做完人只在关键节点确认。架构内幕一次 POST 请求的旅程这套架构其实是被 404 逼出来的。为什么每次请求都要重建一个McpServer实例因为早期实现用进程内内存 Map 保存会话initialize握手在 worker A 上建了会话下一个请求被负载均衡到 worker B后者根本不认识这个会话整个 MCP 握手以 404 MCP session not found 告终对应 GitHub issue #2459注释就写在 Handlers/RouteHandler.ts 的开头。于是现在的旅程长这样① 请求到达路由层。extractApiKey()先从本请求头里读出 API Keyx-api-key或Authorization同时给请求头做一份快照保证后续日志能还原客户端真实发送的内容。② 协议版本协商。SDK 会拒绝任何它不认识的MCP-Protocol-Version头所以对更新的客户端服务器协商到双方共同支持的最新版本并重写请求头对initialize请求则放行让握手自行协商对完全不支持的版本返回 400 并列出支持列表。③ 响应格式协商。根据Accept头决定回application/json单响应体还是 SSE 流遇到不可接受的Accept返回 406 并列出[application/json, text/event-stream]。④ 新建实例。createMCPServerInstance()造一个全新的McpServerregisterToolHandlers()用闭包把本次请求的apiKey绑到工具处理器上——而不是用进程级全局变量避免并发请求互相串 key。⑤ 用完即毁。响应关闭时 transport 与 server 立即close()进程内存不留任何会话。为什么无状态是安全的因为 OneUptime 的工具本身不携带会话状态tools/list来自路由初始化时绑定的工具列表每次tools/call都用同一个请求头里的 API Key 认证。每个请求都是自包含的打到哪个副本都一样。能力全景155 个工具听着吓人其实就是一张矩阵数据库资源统一生成 snake_case 的六件套create_incident、get_incident、list_incidents、update_incident、delete_incident、count_incidents遥测资源只有只读两件套。资源类别CreateGet/List/CountUpdateDelete监控Monitor / Status / Status Event✓✓✓✓事件Incident 及 State、Severity、Timeline、公开/内部备注✓✓✓✓告警Alert 及 State、Severity、Timeline、内部备注✓✓✓✓状态页Status Page / Announcement✓✓✓✓计划维护Scheduled Maintenance Event / State / Timeline✓✓✓✓团队与值班Team / On-Call Policy✓✓✓✓标签Label✓✓✓✓遥测Log / Metric / Span / Exception Instance / Monitor Log—仅 list count——工具自带安全注解只读操作带readOnlyHint删除类带destructiveHint行为良好的客户端会据此自动批准只读调用、对破坏性调用弹确认。但注解只是建议很多客户端会无差别自动批准非只读工具所以 Tools/ToolGenerator.ts 提供了服务端硬裁剪MCP_READ_ONLYtrue仅暴露 read / list / count 工具MCP_ALLOW_DESTRUCTIVEfalse保留 create/update、移除全部 delete 工具。两者均接受true/1/yes不区分大小写默认保持全部工具暴露。 三步接入工具矩阵铺好了接下来看怎么把它接进你的 AI 客户端。第 1 步拿一个项目级 API Key。登录你的 OneUptime 实例进入项目设置Project Settings→ API Keys点击创建 API KeyCreate API Key起名例如 MCP Server按使用场景选择权限只读即可覆盖所有get_/list_/count_工具复制生成的密钥。⚠️ 绝不要把主密钥交给 AI 代理。OneUptime 的主masterAPI Key 同样会被该请求头接受且授予整个实例的管理员权限。始终使用满足最小权限的项目 API Key。第 2 步配置客户端。Claude Desktop 找到配置文件macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.json在文件中加入以下段落把域名换成你的实例即可{ mcpServers: { oneuptime: { transport: streamable-http, url: https://your-oneuptime-domain.com/mcp, headers: { x-api-key: your-api-key-here } } } }VS Code 从 1.99 版本起原生支持 MCP配合 GitHub Copilot需先启用 Copilot Chat按CtrlShiftP/CmdShiftP打开 MCP: Open User Configuration在mcp.json中写入下面这段。它用了password: true的输入变量启动时会以密码方式提示你输入 Key 而不是明文落盘也可以在项目.vscode/mcp.json里做项目级配置之后用 MCP: List Servers 启动 oneuptime 即可{ servers: { oneuptime: { type: http, url: https://your-oneuptime-domain.com/mcp, headers: { x-api-key: ${input:oneuptime-api-key} } } }, inputs: [ { type: promptString, id: oneuptime-api-key, description: OneUptime API Key, password: true } ] }第 3 步可选公共无密钥模式。只想查状态页、拿帮助的话不带 Key 连接即可去掉headers字段{ mcpServers: { oneuptime: { transport: streamable-http, url: https://your-oneuptime-domain.com/mcp } } }补充一个安全细节状态页所有者可以在Status Page → Advanced Settings → MCP Server关闭单个状态页的 MCP 访问默认开启。关闭后四个get_public_status_page_*工具对该页返回错误但状态页网站、RSS 订阅与公共 JSON API 不受影响该页所属项目的认证工具get_status_page、list_status_pages等也照常工作。 端点与协议细节客户端之外运维侧还需要知道服务器上到底开了哪些口子。全部端点如下端点方法描述/mcpPOSTJSON-RPC 请求用于工具调用及其他操作/mcpGET不带 SSEAccept头时返回友好的 JSON 发现负载带 SSE 头时返回405无状态服务器不提供独立 SSE 流合规客户端会忽略它继续工作/mcpDELETE空操作服务器无状态没有会话需要终止/mcp/healthGET健康检查端点/mcp/toolsGET列出可用工具的 REST APIGET 发现负载返回name、status、message、protocolVersions、latestProtocolVersion五个字段——握手失败时不用翻容器日志就能判断协议版本问题。健康检查则返回status: healthy、service、mode: stateless、tools数量、activeSessions: 0及协议版本信息。验证服务器是否在线一条 curl 就够# 健康检查自托管请替换为你的域名 curl https://your-oneuptime-domain.com/mcp/health想看工具全貌再调一次# 列出全部可用工具 curl https://your-oneuptime-domain.com/mcp/tools认证与错误机制有了端点下一个问题是怎么证明你是你。服务器从两个请求头里取密钥允许列表定义在 ServerConfig.ts 中为[x-api-key, authorization]请求头形态解析规则x-api-key直接放 API Key 原文取值即用AuthorizationBearer your-api-key-here按 RFC 7235 不区分大小写正则/^Bearer\s(.)$/i提取没有 Key 也能连但只能用这 6 个公共工具oneuptime_help能力与使用帮助、oneuptime_list_resources资源与操作清单、get_public_status_page_overview、get_public_status_page_incidents、get_public_status_page_scheduled_maintenance、get_public_status_page_announcements。公共状态页工具同时接受状态页 IDUUID或状态页域名。错误处理是这套系统里最值得学习的细节工具执行失败不以 MCP 协议错误抛出而是作为带内结果返回——isError: true加上statusCode、details与suggestion实现在 Handlers/ToolHandler.ts 的buildErrorResult()。为什么不直接用协议级错误因为协议错误对代理来说是个黑盒而带内结果能让代理读到失败原因并自我纠正。状态码与建议的映射状态码建议内容400请求无效对照工具输入 Schema 检查必填参数与值格式details通常会指出具体字段401API Key 被拒确认密钥正确且未过期经x-api-key头发送403密钥权限不足请项目管理员为密钥授予相应权限404资源不存在改用对应的 list 工具查找有效 ID429触发限流稍等片刻后重试 实战场景端点、认证都通了现在把工具组合成真实工作流。事件处置闭环一次标准的事件响应在 AI 手里是一条箭头链list_incidents→acknowledge_incident→list_logs→add_incident_note→resolve_incident这些工作流工具定义在 Tools/WorkflowTools.ts的设计初衷是让代理不需要懂 OneUptime 的数据模型——解决事件在数据层实际意味着创建一条指向项目 Resolved 状态的IncidentStateTimeline记录等价于你在仪表板里点下那个按钮。同理acknowledge_incident/resolve_incident、acknowledge_alert/resolve_alert移动事件与告警状态add_incident_note支持visibility: internal仅团队可见默认与public发布到状态页支持 Markdownadd_alert_note则为告警添加内部备注。代理开工前可以先调oneuptime_whoami拿到 API Key 所属项目的 ID 与名称完成自定位——正因创建类工具会从 Key 推断projectId代理永远不需要显式传项目 ID。遥测查询遥测走 OpenTelemetry 摄取因此不存在创建类工具只有list_logs、list_metrics、list_spans、list_exception_instances、list_monitor_logs及对应count_变体。查询时务必按时间范围过滤并压低 limit10–50 为宜因为遥测表很大{ query: { time: { _type: GreaterThan, value: 2026-07-04T00:00:00.000Z } }, sort: { time: DESC }, limit: 50 }查询字段接受直接值精确匹配或操作符对象共 12 个EqualTo、NotEqual、IsNull、NotNull、EqualToOrNull、GreaterThan、LessThan、GreaterThanOrEqual、LessThanOrEqual、InBetween、Search、Includes排序值为ASC或DESC。这些提示在工具生成时会自动追加到 query 参数描述里即QUERY_OPERATOR_HINT代理不用背文档。列表响应每次都精确报告返回内容hasMore为 true 时还会附带提示Repeat the call with skipN to get the next page.{ returnedCount: 10, totalCount: 42, skip: 0, limit: 10, hasMore: true, data: [...] }自然语言示例最后感受一下用嘴操作的日常形态以下都是可以直接丢给 AI 的话监控器管理Create a new website monitor for https://example.com that checks every 5 minutes. Set up an API monitor for https://api.example.com/health with a 30-second timeout. Change the monitoring interval for my website monitor to every 2 minutes. Disable the monitor for staging.example.com while were doing maintenance.事件管理Create a high-priority incident for the database outage affecting user authentication. Add a note to incident #123 saying Database connection restored, monitoring for stability. Mark incident #456 as resolved.团队与值班List the teams in this project. Show me our on-call policies.状态页管理Update our status page to show Investigating Payment Issues for the payment service. Create a status page announcement about scheduled maintenance this weekend.公共状态页无需 KeyWhats the current status of status.example.com? Show me recent incidents from the OneUptime status page. Are there any scheduled maintenance events on status.acme.com?高级组合Create a scheduled maintenance window for Saturday 2-4 AM, disable all monitors for api.example.com during that time, and update the status page. Show me all monitors that have been down in the last hour, create incidents for any that dont already have one.源码级补充前面的章节讲的是怎么用这一节集中放几个只在源码里才完整的细节方便你排查边界行为。字段选择selectget_/list_工具接受可选的select字段名数组。默认返回除重字段JSON 列、超长文本与 HTML 列之外的所有可读字段重字段必须显式请求buildSelectProperty()会在 Schema 描述中列出默认排除的重字段让代理知道该选什么。受限列自动剔除当受限 API Key 读不到默认全字段 select 中的某一列时API 会拒绝整个请求Services/OneUptimeApiService.ts 会解析错误信息中被拒绝的列名、剔除该列后重试上限MAX_SELECT_PERMISSION_RETRIES即最多 10 次保证最小权限密钥仍能拿到结果。分页常量limit默认 10、最大 100定义于 Config/ServerConfig.ts 的LIST_DEFAULT_LIMIT/LIST_MAX_LIMIT配skip使用。工具生成所有输入 Schema 基于 OneUptime 的ModelSchema/AnalyticsModelSchema生成并转换为 JSON Schema带完整输入校验generateToolsForAnalyticsModel()只为遥测模型产出 list 与 count 工具。安全与权限工具面这么大密钥权限就成了安全边界。一句话对比只授读取权限的 Key 覆盖全部get_/list_/count_查询需要完整创建、更新、删除能力时给 Key 授予项目管理员Project Admin权限。最小权限只授予代理必需的最低权限能用只读 Key 就别给写权限定期轮换按计划更换 API Key缩短泄露后的暴露窗口监控使用在 OneUptime 中跟踪 API Key 的调用情况异常用量及时处置环境隔离不同环境生产 / 预发 / 测试使用不同的 API Key故障互不牵连。故障速查连不上或行为怪异时按这张表排查大多数情况三分钟内定位症状可能原因处置动作权限错误403 类带内错误Key 权限不足列出资源需读取权限创建/更新需写入权限删除需删除权限为 Key 补齐对应权限或改用MCP_READ_ONLY等策略收窄工具面连接失败 / 握手报错URL 拼错、实例不可达、协议版本不匹配核对 URL先打/mcp/health验证可达性再看/mcp的 GET 发现负载确认支持的protocolVersionsAPI Key 无效401Key 有多余空格、已过期或复制错误在设置中核对 Key检查空白字符与过期时间会话相关错误如 404 session客户端携带了旧版本服务器的mcp-session-id头无状态设计不签发也不跟踪 session ID每个请求可打到任意副本旧版客户端的mcp-session-id头会被直接忽略无需处理更新期待 session ID 的旧客户端配置即可 延伸阅读想再往下挖源码都在仓库里只读浏览即可MCP 模块 README 与全部源码packages/App/FeatureSet/MCP无状态路由与端点实现Handlers/RouteHandler.ts工具执行与错误处理Handlers/ToolHandler.ts工具生成与写入策略Tools/ToolGenerator.ts工作流工具定义Tools/WorkflowTools.ts底层 API 调用与受限列重试Services/OneUptimeApiService.ts路由与服务名等常量Config/ServerConfig.ts官方英文文档原文en/ai/mcp-server.md【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考