让 AI 直接接管监控与事件OneUptime MCP 服务器完整指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime MCP 服务器让 AI 助手直接管理监控、事件与可观测性Claude、GitHub Copilot 等客户端可以用自然语言配置监控器、处置事件、查询遥测数据全程无需在本地安装任何东西。跟着往下读你会完成 API Key 创建与客户端配置、跑通健康检查并弄清/mcp端点背后那套无状态架构的来龙去脉。为什么需要 AI 直连监控先还原一个凌晨三点的值班场景告警响了你打开仪表板找到对应事件点已受理翻日志和指标定位原因给状态页发一条公告确认恢复后再点已解决。这几步在 OneUptime 里都有现成按钮但每一步都要人肉点击和切换页面。接入 MCPModel Context Protocol服务器后这条链路可以由 AI 代理替你跑完你用一句帮我受理这个事件查一下最近的日志然后在状态页贴一条更新代理就会依次调用acknowledge_incident、list_logs、add_incident_note、resolve_incident这类工具完成操作。具体能覆盖的日常动作包括创建和配置监控器、查看其状态与状态历史创建、受理、解决事件并添加内部或公开备注管理团队与 on-call 策略管理状态页并发布公告创建计划维护事件以及只读地查询日志、指标、链路trace、异常与监控器日志。MCP 服务器和 OneUptime 实例一起托管通过Streamable HTTP传输对外服务因此你不需要部署任何独立组件云用户https://oneuptime.com/mcp自托管用户https://your-oneuptime-domain.com/mcp服务端实现位于 MCP 模块目录核心是Server/MCPServer.ts中基于modelcontextprotocol/sdk的McpServer实例并声明了工具tools能力。五分钟上手拿到 API Key 并完成首次连接开始之前确认三样东西一个 OneUptime 实例云版或自托管都可以、一个支持 MCP 的客户端、以及一个 API Key——注意只有认证操作才需要密钥公共工具不需要。最短路径如下登录实例进入Project Settings → API Keys → Create API Key起个名字比如MCP Server按最小需求勾选权限记住这个 Key 是项目级作用域的服务器从密钥推断你的项目所以所有创建类工具永远不需要projectId参数在客户端配置里填入 Key下一节给现成 JSON用 curl 验证服务端活着、工具可列# 健康检查云版示例自托管替换域名 curl https://oneuptime.com/mcp/health # 列出可用工具 curl https://oneuptime.com/mcp/tools健康检查会返回status: healthy、service、mode: stateless、工具数量、activeSessions: 0和协议版本信息——activeSessions: 0是常态因为后面会讲这个服务器根本不维护会话。警告 —— 永远不要把主密钥交给 AI 代理。OneUptime 的masterAPI Key 同样会被请求头接受并且授予整个实例的管理员权限。始终用满足代理最小权限的项目 API Key只读密钥就能覆盖全部get_/list_/count_工具。接入你的 AI 客户端Claude Desktop、Copilot 与无密钥公共访问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://oneuptime.com/mcp, headers: { x-api-key: your-api-key-here } } } }关键差异提示Claude Desktop 的配置格式是mcpServerstransport: streamable-httpKey 直接写在 headers 里。VS Code 加 GitHub Copilot 完整配置VS Code 从1.99版本起原生支持 MCP 服务器。按CtrlShiftPmacOS 为CmdShiftP→ 输入 MCP: Open User Configuration 回车打开或创建mcp.json也可以在项目里放.vscode/mcp.json做工作区级配置{ servers: { oneuptime: { type: http, url: https://oneuptime.com/mcp, headers: { x-api-key: ${input:oneuptime-api-key} } } }, inputs: [ { type: promptString, id: oneuptime-api-key, description: OneUptime API Key, password: true } ] }关键差异提示这里用password: true的promptString输入变量代替明文——Key 不落盘首次启动服务器时按提示输入VS Code 会先要求你确认信任。之后在 MCP: List Servers 里点击oneuptime启动即可。无密钥公共访问怎么开如果只需要状态页信息和帮助类工具可以完全不配 headers{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp } } }这样就能免认证使用公共状态页工具和oneuptime_help、oneuptime_list_resources。另外状态页所有者可以在Status Page → Advanced Settings → MCP Server单独关闭某个状态页的 MCP 访问默认开启关闭后四个get_public_status_page_*工具对该页返回错误但状态页网站、RSS 订阅和公共 JSON API 不受影响该页所属项目自己的认证工具也照常工作。能力全景约 155 个工具覆盖 22 类资源整个工具面由约155 个工具组成覆盖22 类资源。数据库类资源每类都有create_、get_、list_、update_、delete_、count_六种操作例如create_incident、list_incidents、count_incidents遥测类资源只暴露list_与count_。资源与工具命名监控Monitor、Monitor Status、Monitor Status Event事件Incident、Incident State、Incident Severity、Incident State Timeline、Incident Public Note、Incident Internal Note告警Alert、Alert State、Alert Severity、Alert State Timeline、Alert Internal Note状态页Status Page、Status Page Announcement计划维护Scheduled Maintenance Event、Scheduled Maintenance State、Scheduled Maintenance State Timeline团队与值班Team、On-Call Policy标签Label遥测只读Log、Metric、Span、Exception Instance、Monitor Log——例如list_logs、count_spans因为数据经 OpenTelemetry 摄取不存在创建类工具在此之上还有一组专为响应流程设计的工作流工具acknowledge_incident/resolve_incident、acknowledge_alert/resolve_alert、add_incident_notevisibility取internal默认或public公开备注会发布到状态页支持 Markdown、add_alert_note外加身份工具oneuptime_whoami与辅助工具oneuptime_help、oneuptime_list_resources。对外暴露的 HTTP 端点端点方法说明/mcpPOSTJSON-RPC 入口所有工具调用与 MCP 操作都走这里/mcpGET不带 SSEAccept头时返回友好的 JSON 发现负载带 SSE 头时返回405——无状态模式下不提供独立 SSE 流/mcpDELETE空操作服务器无状态没有会话需要终止/mcp/healthGET健康检查附带本构建支持的协议版本/mcp/toolsGETREST 风格列出全部可用工具GET 发现负载包含name、status、message、protocolVersions与latestProtocolVersion字段方便不翻容器日志就诊断失败的握手。安全注解readOnlyHint 与 destructiveHint工具生成为每个get_/list_/count_工具打上readOnlyHint为每个delete_工具打上destructiveHint逻辑在 ToolGenerator.ts 的getAnnotationsForOperation()中。MCP 客户端据此自动批准安全调用、对破坏性调用要求人工确认——但这些注解只是建议真正想硬性裁剪工具面要看后面认证与权限一章的两个环境变量。 五分钟之后的深度设计揭秘与排雷先说结论这个服务器不记得任何会话。每请求新建实例、处理、销毁在 RouteHandler.ts 的注释里明确写着每次 POST 请求都会新建一个McpServer实例与StreamableHTTPServerTransport处理完该请求后立即销毁进程内存中不保留任何会话状态。Server/MCPServer.ts中的createMCPServerInstance()每次都创建全新实例而Handlers/ToolHandler.ts中registerToolHandlers()通过闭包把本次请求的apiKey绑定到工具处理器上——这就避免了并发请求下进程级全局 API Key的竞态。为什么必须如此注释里引用了一节历史教训对应 GitHub issue #2459早期实现用进程内内存 Map 保存会话OneUptime 以多副本部署时initialize握手在一个 worker 上创建会话后续请求被负载均衡到另一个 worker对方根本不认识这个会话于是整个握手失败报404 MCP session not found。无状态之所以安全是因为 OneUptime 的工具本身不携带会话状态tools/list来自路由初始化时绑定的工具列表每次tools/call都直接用同一请求头里的 API Key 认证。协议版本与响应格式的两层协商请求到达 SDK 传输层之前TransportNegotiation.ts 做两层兼容性协商协议版本协商SDK 会拒绝任何不认识的MCP-Protocol-Version头。对比内置 SDK 更新的客户端服务器协商到双方共同支持的最新版本并重写请求头initialize请求直接放行让握手自行协商完全不支持的版本返回400并列出支持的版本列表。响应格式协商看客户端的Accept头决定返回application/json单响应体enableJsonResponse: true还是 SSE 流两者都不接受时返回406并列出支持类型[application/json, text/event-stream]。认证与权限公共工具、项目 Key 与最小权限无需认证也能用的公共工具oneuptime_helpMCP 能力使用帮助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或域名两种写法都接受两种认证请求头其余所有操作都需要密钥走以下任一请求头允许的认证头在 ServerConfig.ts 中定义为[x-api-key, authorization]x-api-key直接放 KeyAuthorizationBearer your-api-key-here方案不区分大小写——RouteHandler.ts的extractApiKey()用/^Bearer\s(.)$/i解析工具错误以带内结果返回isError: true带statusCode、details与suggestion三个字段而不是 MCP 协议错误——这样代理能读到失败原因并自我纠正。getSuggestionForStatusCode()为常见状态码预置了建议400参数校验失败、401密钥被拒、403权限不足、404资源不存在建议用 list 工具找 ID、429限流稍后重试。权限分级与两个服务端硬开关只读访问Key 只加读取权限即可用全部get_/list_/count_工具完全访问需要创建、更新、删除能力时给 Key **项目管理员Project Admin**权限最佳实践最小权限、定期轮换密钥、监控 Key 使用情况、不同环境用不同 Key。注解毕竟只是建议很多客户端会无差别自动批准非只读工具。为此 ToolGenerator.ts 提供两个运维级环境变量在服务端硬性裁剪工具面MCP_READ_ONLYtrue仅暴露 read / list / count 工具MCP_ALLOW_DESTRUCTIVEfalse保留 create/update但移除所有 delete 工具。两者都接受true/1/yes不区分大小写默认保持全部工具暴露。实战日常指令怎么写接入之后指令就是一句人话。按场景给你几组可以直接抄的写法监控器给我的生产域名加一个每 5 分钟探测一次的网站监控器建完把它的当前状态报给我staging 环境要做维护把它的监控器停掉维护完再自动恢复事件数据库断连影响了登录开一个高优先级事件先受理等连接恢复后把事件标记为已解决给那个支付网关事件补一条公开备注正在排查预计 30 分钟内更新团队与值班这个项目里有哪些团队各自的 on-call 策略是什么下周二轮到谁值班状态页状态页给支付服务贴一条调查中再发一条本周末计划维护的公告公共查询无需 API Keystatus.example.com 现在是什么状态最近有什么事件高级组合找出过去一小时宕机过的所有监控器对还没有事件的那些自动建事件值得知道的一层机制resolve_incident背后的真实动作是创建一条指向项目 Resolved 状态的IncidentStateTimeline记录——工作流工具的设计初衷就是让代理不用了解 OneUptime 数据模型内部。一个典型处置循环是list_incidents→acknowledge_incident→ 用list_logs调查 →add_incident_note公开→resolve_incident。进阶遥测查询语法、分页与字段选择日志、指标、链路、异常与监控器日志以只读list_和count_工具暴露list_logs、list_metrics、list_spans、list_exception_instances、list_monitor_logs及对应count_变体。ToolGenerator.ts的generateToolsForAnalyticsModel()只为遥测模型生成 list 与 count并在描述里反复提醒遥测表很大务必按时间范围过滤limit 保持 10–50 这种小值。时间范围与操作符查询字段可以直接给值也可以给操作符对象{ query: { time: { _type: GreaterThan, value: 2026-07-04T00:00:00.000Z } }, sort: { time: DESC }, limit: 50 }操作符全集EqualTo、NotEqual、IsNull、NotNull、EqualToOrNull、GreaterThan、LessThan、GreaterThanOrEqual、LessThanOrEqual、InBetween、Search、Includes。排序值只有ASC和DESC。这些提示会在工具生成时自动追加到 query 参数描述中ToolGenerator.ts的QUERY_OPERATOR_HINT。oneuptime_whoami代理的自检首调oneuptime_whoami返回当前 API Key 所属项目的 ID 与名称。由于创建类工具会从密钥推断projectId代理永远不需要显式传项目 ID——这个工具就是它确认自己在哪个项目的第一调。分页协议与重字段 select列表工具的limit默认10、最大100常量在 ServerConfig.ts配合skip翻页。每次列表响应都精确报告返回内容returnedCount、totalCount、skip、limit、hasMore和data当hasMore为 true 时还会附带提示Repeat the call with skipN to get the next page.。get_和list_工具接受可选的select字段名数组。默认返回所有可读字段除重字段外——JSON 列、超长文本与 HTML 列必须显式在select里请求buildSelectProperty()会在 Schema 描述中列出被默认排除的重字段。还有一个容易踩的边界受限 API Key 无法读取默认全字段 select 中的某一列时API 会拒绝整个请求。OneUptimeApiService.ts 的处理是自动剔除该列并重试最多 10 次MAX_SELECT_PERMISSION_RETRIES保证最小权限密钥仍能拿到结果。️ 排雷手册常见错误与解决办法现象原因解决办法401/403权限错误Key 权限不足或已被拒列出资源需读取权限创建/更新需写入权限删除需删除权限按最小权限补齐对应权限连接失败、超时域名写错或实例不可达核对 OneUptime URL、确认实例在线再打一次/mcp/health验证Key 无效多余空格、字符或已过期回设置页核对x-api-key的原始值注意首尾空格过期就重新生成会话类报错如旧客户端一直发mcp-session-id头服务器是无状态的不签发也不跟踪会话 ID直接省略该头即可它会被忽略把期待会话 ID 的旧版 MCP 客户端配置升级到无状态模式源码地图与延伸阅读想验证本文任何结论按下表定位即可模块根目录packages/App/FeatureSet/MCP测试在Tests/子目录随 App 测试套件运行MCP 模块根目录与 README传输、端点、工具目录与协议兼容性的总览Server/MCPServer.tscreateMCPServerInstance()每请求新建McpServer实例Config/ServerConfig.ts服务名oneuptime-mcp、路由前缀/mcp、认证头清单、limit默认/上限常量Handlers/RouteHandler.ts无状态路由、五个端点、extractApiKey()与协议版本协商的注释出处Handlers/ToolHandler.tsregisterToolHandlers()闭包绑定 apiKey、formatListResponse()分页提示、带内错误与getSuggestionForStatusCode()Tools/ToolGenerator.ts从ModelSchema生成 JSON Schema、安全注解、MCP_READ_ONLY/MCP_ALLOW_DESTRUCTIVE写入策略、QUERY_OPERATOR_HINTTools/WorkflowTools.tsacknowledge/resolve 与备注类工作流工具Tools/HelperTools.tsoneuptime_help、oneuptime_list_resourcesTools/PublicStatusPageTools.ts四个免认证公共状态页工具Services/OneUptimeApiService.ts底层 API 调用、受限 Key 的剔除列重试上限 10 次Utils/TransportNegotiation.ts协议版本与Accept头的两层协商官方英文文档仓库内文档的英文原文与本文事实互为印证【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考