让 AI 直接接管监控与事件：OneUptime MCP 服务器完整指南

让 AI 直接接管监控与事件：OneUptime MCP 服务器完整指南

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

OneUptime MCP 服务器让 AI 助手直接管理监控、事件与可观测性：Claude、GitHub Copilot 等客户端可以用自然语言配置监控器、处置事件、查询遥测数据，全程无需在本地安装任何东西。跟着往下读，你会完成 API Key 创建与客户端配置、跑通健康检查，并弄清/mcp端点背后那套无状态架构的来龙去脉。

为什么需要 AI 直连监控

先还原一个凌晨三点的值班场景：告警响了，你打开仪表板找到对应事件，点"已受理"，翻日志和指标定位原因，给状态页发一条公告，确认恢复后再点"已解决"。这几步在 OneUptime 里都有现成按钮，但每一步都要人肉点击和切换页面。

接入 MCP（Model 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——注意只有认证操作才需要密钥，公共工具不需要。

最短路径如下：

1. 登录实例，进入Project Settings → API Keys → Create API Key，起个名字（比如MCP Server），按最小需求勾选权限；
2. 记住这个 Key 是项目级作用域的：服务器从密钥推断你的项目，所以所有创建类工具永远不需要projectId参数；
3. 在客户端配置里填入 Key（下一节给现成 JSON）；
4. 用 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.json，Windows 在%APPDATA%\Claude\claude_desktop_config.json，Linux 在~/.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 的配置格式是mcpServers+transport: "streamable-http"，Key 直接写在 headers 里。

VS Code 加 GitHub Copilot 完整配置

VS Code 从1.99版本起原生支持 MCP 服务器。按Ctrl+Shift+P（macOS 为Cmd+Shift+P）→ 输入 "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_note（visibility取"internal"默认或"public"，公开备注会发布到状态页，支持 Markdown）、add_alert_note，外加身份工具oneuptime_whoami与辅助工具oneuptime_help、oneuptime_list_resources。

对外暴露的 HTTP 端点

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 做两层兼容性协商：

1. 协议版本协商：SDK 会拒绝任何不认识的MCP-Protocol-Version头。对比内置 SDK 更新的客户端，服务器协商到双方共同支持的最新版本并重写请求头；initialize请求直接放行让握手自行协商；完全不支持的版本返回400并列出支持的版本列表。
2. 响应格式协商：看客户端的Accept头决定返回application/json单响应体（enableJsonResponse: true）还是 SSE 流；两者都不接受时返回406并列出支持类型["application/json", "text/event-stream"]。

认证与权限：公共工具、项目 Key 与最小权限

无需认证也能用的公共工具

• oneuptime_help：MCP 能力使用帮助
• oneuptime_list_resources：列出可用资源及其操作
• get_public_status_page_overview/get_public_status_page_incidents/get_public_status_page_scheduled_maintenance/get_public_status_page_announcements：四个公共状态页工具，状态页 ID（UUID）或域名两种写法都接受

两种认证请求头

其余所有操作都需要密钥，走以下任一请求头（允许的认证头在 ServerConfig.ts 中定义为["x-api-key", "authorization"]）：

• x-api-key：直接放 Key
• Authorization：Bearer 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_ONLY=true：仅暴露 read / list / count 工具；
• MCP_ALLOW_DESTRUCTIVE=false：保留 create/update，但移除所有 delete 工具。

两者都接受true/1/yes（不区分大小写），默认保持全部工具暴露。

实战：日常指令怎么写

接入之后，指令就是一句人话。按场景给你几组可以直接抄的写法：

监控器

• "给我的生产域名加一个每 5 分钟探测一次的网站监控器，建完把它的当前状态报给我"
• "staging 环境要做维护，把它的监控器停掉，维护完再自动恢复"

事件

• "数据库断连影响了登录，开一个高优先级事件，先受理，等连接恢复后把事件标记为已解决"
• "给那个支付网关事件补一条公开备注：正在排查，预计 30 分钟内更新"

团队与值班

• "这个项目里有哪些团队？各自的 on-call 策略是什么"
• "下周二轮到谁值班"

状态页

• "状态页给支付服务贴一条'调查中'，再发一条本周末计划维护的公告"

公共查询（无需 API Key）

• "status.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 skip=N to get the next page.。

get_和list_工具接受可选的select字段名数组。默认返回所有可读字段除重字段外——JSON 列、超长文本与 HTML 列必须显式在select里请求，buildSelectProperty()会在 Schema 描述中列出被默认排除的重字段。

还有一个容易踩的边界：受限 API Key 无法读取默认"全字段" select 中的某一列时，API 会拒绝整个请求。OneUptimeApiService.ts 的处理是自动剔除该列并重试，最多 10 次（MAX_SELECT_PERMISSION_RETRIES），保证最小权限密钥仍能拿到结果。

🛠️ 排雷手册：常见错误与解决办法

源码地图与延伸阅读

想验证本文任何结论，按下表定位即可（模块根目录packages/App/FeatureSet/MCP，测试在Tests/子目录，随 App 测试套件运行）：

• MCP 模块根目录与 README：传输、端点、工具目录与协议兼容性的总览
• Server/MCPServer.ts：createMCPServerInstance()，每请求新建McpServer实例
• Config/ServerConfig.ts：服务名oneuptime-mcp、路由前缀/mcp、认证头清单、limit默认/上限常量
• Handlers/RouteHandler.ts：无状态路由、五个端点、extractApiKey()与协议版本协商的注释出处
• Handlers/ToolHandler.ts：registerToolHandlers()闭包绑定 apiKey、formatListResponse()分页提示、带内错误与getSuggestionForStatusCode()
• Tools/ToolGenerator.ts：从ModelSchema生成 JSON Schema、安全注解、MCP_READ_ONLY/MCP_ALLOW_DESTRUCTIVE写入策略、QUERY_OPERATOR_HINT
• Tools/WorkflowTools.ts：acknowledge/resolve 与备注类工作流工具
• Tools/HelperTools.ts：oneuptime_help、oneuptime_list_resources
• Tools/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