企业官网建设流程全解析

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

为什么需要它

你有没有经历过这种循环：故障发生，你从监控平台切到告警群、再切到状态页、再切到值班表，手动点一圈按钮才算"响应"完了。真正消耗时间的不是点击，而是每次切换时丢失的上下文。

MCP（Model 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 的开头）。

于是现在的旅程长这样：

1. ① 请求到达路由层。extractApiKey()先从本请求头里读出 API Key（x-api-key或Authorization），同时给请求头做一份"快照"，保证后续日志能还原客户端真实发送的内容。
2. ② 协议版本协商。SDK 会拒绝任何它不认识的MCP-Protocol-Version头，所以对更新的客户端，服务器协商到双方共同支持的最新版本并重写请求头；对initialize请求则放行让握手自行协商；对完全不支持的版本返回 400 并列出支持列表。
3. ③ 响应格式协商。根据Accept头决定回application/json单响应体还是 SSE 流；遇到不可接受的Accept返回 406 并列出["application/json", "text/event-stream"]。
4. ④ 新建实例。createMCPServerInstance()造一个全新的McpServer，registerToolHandlers()用闭包把本次请求的apiKey绑到工具处理器上——而不是用进程级全局变量，避免并发请求互相串 key。
5. ⑤ 用完即毁。响应关闭时 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），遥测资源只有只读两件套。

工具自带安全注解：只读操作带readOnlyHint，删除类带destructiveHint，行为良好的客户端会据此自动批准只读调用、对破坏性调用弹确认。但注解只是"建议"，很多客户端会无差别自动批准非只读工具，所以 Tools/ToolGenerator.ts 提供了服务端硬裁剪：MCP_READ_ONLY=true仅暴露 read / list / count 工具；MCP_ALLOW_DESTRUCTIVE=false保留 create/update、移除全部 delete 工具。两者均接受true/1/yes（不区分大小写），默认保持全部工具暴露。

🚀 三步接入

工具矩阵铺好了，接下来看怎么把它接进你的 AI 客户端。

第 1 步：拿一个项目级 API Key。

1. 登录你的 OneUptime 实例；
2. 进入项目设置（Project Settings）→ API Keys；
3. 点击创建 API Key（Create API Key）；
4. 起名，例如 "MCP Server"；
5. 按使用场景选择权限（只读即可覆盖所有get_/list_/count_工具）；
6. 复制生成的密钥。

⚠️ 绝不要把主密钥交给 AI 代理。OneUptime 的主（master）API Key 同样会被该请求头接受，且授予整个实例的管理员权限。始终使用满足最小权限的项目 API Key。

第 2 步：配置客户端。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://your-oneuptime-domain.com/mcp", "headers": { "x-api-key": "your-api-key-here" } } } }

VS Code 从 1.99 版本起原生支持 MCP（配合 GitHub Copilot，需先启用 Copilot Chat）：按Ctrl+Shift+P/Cmd+Shift+P打开 "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等）也照常工作。

🔌 端点与协议细节

客户端之外，运维侧还需要知道服务器上到底开了哪些口子。全部端点如下：

GET 发现负载返回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"]）：

没有 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。公共状态页工具同时接受状态页 ID（UUID）或状态页域名。

错误处理是这套系统里最值得学习的细节：工具执行失败不以 MCP 协议错误抛出，而是作为带内结果返回——isError: true加上statusCode、details与suggestion（实现在 Handlers/ToolHandler.ts 的buildErrorResult()）。为什么不直接用协议级错误？因为协议错误对代理来说是个黑盒，而带内结果能让代理"读"到失败原因并自我纠正。状态码与建议的映射：

🛠 实战场景

端点、认证都通了，现在把工具组合成真实工作流。

事件处置闭环

一次标准的事件响应在 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"（发布到状态页），支持 Markdown；add_alert_note则为告警添加内部备注。代理开工前可以先调oneuptime_whoami拿到 API Key 所属项目的 ID 与名称完成自定位——正因创建类工具会从 Key 推断projectId，代理永远不需要显式传项目 ID。

遥测查询

遥测走 OpenTelemetry 摄取，因此不存在创建类工具，只有list_logs、list_metrics、list_spans、list_exception_instances、list_monitor_logs及对应count_变体。查询时务必按时间范围过滤并压低 limit（10–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 skip=N 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 we're 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."

公共状态页（无需 Key）"What's 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 don't already have one."

源码级补充

前面的章节讲的是"怎么用"，这一节集中放几个只在源码里才完整的细节，方便你排查边界行为。

• 字段选择（select）：get_/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）权限。

1. 最小权限：只授予代理必需的最低权限，能用只读 Key 就别给写权限；
2. 定期轮换：按计划更换 API Key，缩短泄露后的暴露窗口；
3. 监控使用：在 OneUptime 中跟踪 API Key 的调用情况，异常用量及时处置；
4. 环境隔离：不同环境（生产 / 预发 / 测试）使用不同的 API Key，故障互不牵连。

故障速查

连不上或行为怪异时，按这张表排查，大多数情况三分钟内定位：

📚 延伸阅读

想再往下挖，源码都在仓库里（只读浏览即可）：

• 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