OneUptime MCP 服务器接入指南用 AI 助手驱动监控、事件响应与可观测性【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读OneUptime 内置了基于 Model Context ProtocolMCP的 AI 接入层——MCP 服务器。它作为大型语言模型LLM与 OneUptime 实例之间的桥梁让 Claude、VS CodeGitHub Copilot等 MCP 兼容客户端通过约 155 个工具直接管理监控器、事件、告警、状态页、值班与遥测数据。本文基于 App/FeatureSet/Docs/Content/es/ai/mcp-server.md 与 App/FeatureSet/MCP 模块源码完整讲解其工作原理、配置方式、认证机制、工具清单与实战用法读完即可在自己的 Cloud 或自托管实例上接入并安全使用。什么是 OneUptime MCP 服务器MCP 服务器是 LLM 与 OneUptime 之间的桥接组件实现了 Model Context Protocol。它把 OneUptime 的监控与事件响应能力封装成一组可被 AI 代理直接调用的工具使 AI 助手能够以自然语言指令完成真实的运维操作。它的工作方式非常轻量托管在实例内服务器随 App 容器一同运行通过 Streamable HTTP 传输协议暴露在/mcp端点无需本地安装任何客户端组件云用户端点https://oneuptime.com/mcp自托管用户端点https://your-oneuptime-domain.com/mcp由 App 容器在 Nginx 之后提供无需单独部署。从源码看路由前缀在 App/FeatureSet/MCP/Config/ServerConfig.ts 中被定义为ROUTE_PREFIXES: string[] [/mcp]并在 App/Index.ts 中随MCPRoutes.init()挂载进 App 服务。核心特性约 155 个工具覆盖 22 种数据库资源类型的完整 CRUD 工具事件、告警、监控器、状态页、值班等加上只读遥测工具以及工作流与辅助工具实时操作对资源的创建、读取、更新、删除均可即时完成类型安全接口全部工具基于模型 Schema 生成带完备的输入校验安全认证按请求携带 API 密钥x-api-key头或 Bearer 令牌并妥善处理错误安全注解只读工具带readOnlyHint删除类工具带destructiveHintMCP 客户端可据此自动批准安全调用、对破坏性调用先征求确认易集成兼容 Claude Desktop 与其他 MCP 客户端无状态设计不发放会话 ID每次请求自包含可安全部署在负载均衡器与多副本环境之后。无状态设计是这套实现的关键。在 App/FeatureSet/MCP/Handlers/RouteHandler.ts 中每一次 POST 请求都会新建一个McpServer与StreamableHTTPServerTransport显式省略sessionIdGenerator请求处理完即销毁进程内不保留任何会话状态——因此多副本部署下连续请求落在不同 worker 上也能正常工作。正如该文件注释所述早期基于进程内内存 Map 的有状态实现在多副本部署如 oneuptime.com 本身时曾导致握手阶段出现 “404 MCP session not found” 故障。你能用 AI 做什么接入后AI 助手可以替你完成监控器管理创建与配置监控器、查看其状态、回溯状态历史事件响应创建、确认Acknowledge、解决事件添加内部/公开备注跟踪解决进度团队运维管理团队与值班策略On-Call Policy状态页管理状态页、发布公告Announcement告警确认与解决告警、添加告警备注、管理告警状态与严重级别计划维护创建与管理计划维护事件遥测查询日志、指标、链路Span、异常与监控器日志只读。前置要求一个 OneUptime 实例云版或自托管均可一个 MCP 兼容客户端Claude Desktop、VS Code GitHub Copilot 等有效的 OneUptime API 密钥仅认证操作需要公开工具无需密钥即可工作。获取 API 密钥登录 OneUptime 实例进入设置Settings→ API 密钥API Keys点击创建 API 密钥Create API Key填写名称例如MCP Server按实际用例选择适当的权限复制生成的密钥。密钥是项目级作用域的MCP 服务器从密钥推断项目归属因此所有创建类工具都不需要传projectId参数。这一点在 App/FeatureSet/MCP/Tools/WorkflowTools.ts 的oneuptime_whoami工具描述中也有明确说明。警告——永远不要把主密钥Master Key交给 AI 代理。OneUptime 的masterAPI 密钥也会被此请求头接受且拥有整个实例的管理员级访问权限。务必始终使用项目级、最小权限的 API 密钥只读密钥即可满足所有get_/list_/count_工具并在 App/FeatureSet/MCP/README.md 中再次强调同一安全约定。客户端配置配置 Claude DesktopClaude Desktop 的配置文件位置macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.jsonOneUptime Cloud 配置{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp, headers: { x-api-key: your-api-key-here } } } }自托管配置将oneuptime.com替换为你的 OneUptime 域名{ mcpServers: { oneuptime: { transport: streamable-http, url: https://your-oneuptime-domain.com/mcp, headers: { x-api-key: your-api-key-here } } } }公开访问不带密钥如果只想使用公开工具状态页信息、帮助等可以省略密钥{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp } } }该配置允许无需认证即可访问公开的状态页工具与帮助资源。VS Code GitHub CopilotVS Code 从 1.99 版本起原生支持 MCP 服务器使 Copilot 可以直接访问 OneUptime 数据。第 1 步前置条件VS Code 1.99 或更高版本已安装并启用的 GitHub Copilot 扩展已启用 GitHub Copilot Chat。第 2 步打开 MCP 配置按CtrlShiftPWindows/Linux或CmdShiftPmacOS输入 “MCP: Open User Configuration” 并回车这会打开或创建mcp.json配置文件。也可以在项目工作区创建.vscode/mcp.json实现项目级配置。Cloud 版配置{ 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 } ] }自托管版配置{ 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 步启动 MCP 服务器按CtrlShiftP/CmdShiftP输入 “MCP: List Servers” 查看可用服务器点击 “oneuptime” 启动服务器按提示输入你的 OneUptime API 密钥。第 4 步在 Copilot Chat 中使用打开 GitHub Copilot Chat使用代理模式workspace或直接提问What monitors do I have in OneUptime? Show me recent incidents Create a new monitor for https://example.com安全说明上述配置使用password: true的输入变量安全地提示你输入 API 密钥而不是以明文存储。首次启动 MCP 服务器时 VS Code 会要求信任确认。HTTP 端点一览端点方法说明/mcpPOSTJSON-RPC 请求用于工具调用及其他 MCP 操作/mcpGET无 SSEAccept头时返回友好的 JSON 发现负载带 SSE 头时返回405——无状态服务器不提供独立 SSE 流符合规范的客户端会继续工作/mcpDELETE无副作用无状态没有需要终止的会话/mcp/healthGET健康检查端点同时返回本构建支持的协议版本列表/mcp/toolsGETREST 接口列出全部可用工具这些端点的行为在 App/FeatureSet/MCP/Handlers/RouteHandler.ts 中逐一实现GET 无 SSE 时返回包含protocolVersions与latestProtocolVersion的发现负载健康检查则额外报告mode: stateless、工具数量与activeSessions: 0RouteHandler.ts。值得一提的协议兼容层由于真实世界的 MCP 客户端比 SDK 参考实现更严格也更宽松App/FeatureSet/MCP/Utils/TransportNegotiation.ts 会在请求进入 SDK 之前做两层协商——协议版本协商MCP-Protocol-Version请求头会被协商到双方都支持的最高版本比服务器更新的版本会被降级到服务器最新版本完全无法兼容的版本则返回400并列出支持版本清单而不是在传输层静默失败响应格式协商根据客户端的Accept头选择text/event-streamSSE或纯application/json响应体两者都是 MCP 规范中 POST 的合法答复若客户端两者都不接受则返回406。认证机制MCP 服务器支持两种运行模式公开工具无需认证不带 API 密钥也能连接服务器并使用公开工具oneuptime_help获取关于 OneUptime 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获取公开状态页公告。公开状态页工具接受状态页 IDUUID或状态页域名两种标识。在 App/FeatureSet/MCP/Tools/PublicStatusPageTools.ts 中输入会被严格校验为 UUID 或主机名格式防止路径穿越等构造值触达其他端点同时通过StatusPageService.isMcpServerEnabled检查状态页是否开放 MCP 访问PublicStatusPageTools.ts且“不存在”与“已禁用”返回同一错误信息避免被无密钥调用方枚举状态页。认证工具需要 API 密钥除公开工具外的所有操作监控器、事件、团队管理等都需要通过以下任一请求头认证x-api-key你的 OneUptime API 密钥Authorization带密钥的 Bearer 令牌例如Bearer your-api-key-here。Bearer方案不区分大小写RouteHandler.ts 中用/^Bearer\s(.)$/i匹配。密钥从请求头中即时读取extractApiKey服务器端不配置任何环境变量密钥每次请求自携带——这保证了多副本环境下的安全一致性。错误处理设计工具错误以带内工具结果返回isError: true携带statusCode、details和一条suggestion建议而不是作为 MCP 协议层错误抛出这样代理可以读取失败原因并自我修正。对应的底层异常类型OneUptimeApiError定义在 App/FeatureSet/MCP/Services/OneUptimeApiService.ts携带 HTTP 状态码与原始响应体。工作流工具除每个资源的 CRUD 工具外服务器还包含专门为事件与告警响应设计的工作流工具手写实现见 App/FeatureSet/MCP/Tools/WorkflowTools.tsacknowledge_incident/resolve_incident将事件移动到项目的“已确认”或“已解决”状态——等价于在控制台点击按钮acknowledge_alert/resolve_alert对告警执行同样操作add_incident_note为事件添加备注visibility: internal仅团队可见默认值或visibility: public发布到状态页。支持 Markdownadd_alert_note为告警添加内部备注。这些工具的底层实现非常巧妙源码注释说明解决一个事件本质上意味着创建一条指向项目 “Resolved” 状态的IncidentStateTimeline记录。changeState会先查询项目中isAcknowledgedState/isResolvedState为真的状态行再向/incident-state-timeline或/alert-state-timeline写入一条新记录WorkflowTools.ts——这与控制台按钮做的事完全一致从而让代理无需了解 OneUptime 内部数据模型即可正确操作。所有工作流工具对 ID 都做严格 UUID 校验ObjectID.isValidUUID。一个典型的事件响应闭环list_incidents→acknowledge_incident→ 用list_logs调查 →add_incident_note公开→resolve_incident身份确认oneuptime_whoamioneuptime_whoami返回你的 API 密钥所属的项目ID 与名称。它是代理用来定位自身上下文的最有用首发调用——由于创建类工具从密钥推断projectId代理永远不需要手动传入项目 ID。实现上它查询/api/project/get-list并返回projects数组WorkflowTools.ts。遥测查询只读日志、指标、链路spans、异常与监控器日志以只读的list_与count_工具暴露list_logs、list_metrics、list_spans、list_exception_instances、list_monitor_logs及其count_对应物。遥测数据通过 OpenTelemetry 摄入因此没有创建类工具——这是有意设计App/FeatureSet/MCP/README.md。务必使用时间范围过滤遥测查询。查询字段接受直接值或操作符对象{ 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。这些操作符语法同样会作为提示注入到每个查询参数的工具描述中帮助代理自行发现见 App/FeatureSet/MCP/Tools/ToolGenerator.ts。字段选择与分页get_与list_工具接受可选的select字段名数组。默认返回除重型字段JSON、超长文本、HTML 列外的全部可读字段重型字段需在select中显式请求。列表工具通过limit默认 10最大 100与skip分页常量定义于 App/FeatureSet/MCP/Config/ServerConfig.ts每次列表响应都会如实报告本次返回内容{ returnedCount: 10, totalCount: 42, skip: 0, limit: 10, hasMore: true, data: [...] }值得注意的一个实现细节当最小权限密钥无法读取默认 “all fields” select 中的某些列时OneUptime API 会拒绝整个请求。为此 App/FeatureSet/MCP/Services/OneUptimeApiService.ts 实现了自动降级重试解析出被拒列名、从 select 中删除该列后重试最多 10 次确保最小权限密钥依然能拿到结果。验证服务器状态# OneUptime Cloud curl https://oneuptime.com/mcp/health # 自托管 curl https://your-oneuptime-domain.com/mcp/health列出可用工具# OneUptime Cloud curl https://oneuptime.com/mcp/tools # 自托管 curl https://your-oneuptime-domain.com/mcp/tools实战示例以下自然语言指令可直接交给已接入的 AI 助手执行基础信息查询Whats the current status of all my monitors? Show me incidents from the last 24 hours监控器管理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 Assign the current payment gateway incident to the infrastructure team团队与值班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公开状态页查询无需密钥Whats 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? Get the latest announcements from my public status page with ID abc123-...进阶组合操作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 oneAPI 密钥权限管理只读访问仅查看数据时为密钥添加读取权限即可。完全访问如需创建、更新、删除资源的完全能力确保密钥拥有项目管理员权限。最佳实践最小权限只授予代理实际需要的最小权限定期轮换定期轮换 API 密钥监控用量在 OneUptime 中跟踪密钥使用情况环境隔离为不同环境使用不同密钥。另外从源码可见服务器端对最小权限密钥有很好的兼容性——包括上述 select 列权限降级重试以及带内错误返回都会引导最小权限代理自动规避无权限字段。故障排查权限错误确认 API 密钥具备所需权限列出资源需要读取权限创建/更新资源需要写入权限删除资源需要删除权限。连接问题确认 OneUptime 实例 URL 正确检查 API 密钥有效确保 OneUptime 实例可访问先测试健康检查端点。无效 API 密钥在 OneUptime 设置中核对密钥检查是否有多余空格或字符确认密钥未过期。会话相关错误如果遇到会话相关报错请记住MCP 服务器无状态——不发放也不跟踪会话 ID每次请求可命中任意副本从旧版本服务器带mcp-session-id头的客户端可以直接忽略该头服务器会忽略它更新期待服务器返回会话 ID 的旧 MCP 客户端配置。可用资源总览MCP 服务器为以下资源提供工具监控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监控器日志每个数据库资源通过 snake_case 命名支持 Create、Get、List、Update、Delete、Count 六种操作例如create_incident、get_incident、list_incidents、update_incident、delete_incident、count_incidents。遥测资源只暴露list_与count_工具如list_logs、count_spans。从工具生成机制看App/FeatureSet/MCP/Tools/ToolGenerator.ts 会扫描全部数据库模型与分析模型自动为每个启用的模型生成上述六类工具操作注解按类型自动分配——只读操作Read/List/Count加readOnlyHint更新操作加idempotentHint删除操作同时加destructiveHint与idempotentHintToolGenerator.ts。新模型接入 MCP 只需给数据库模型加上EnableMCP装饰器或为分析模型设置enableMCP下次启动时工具生成器便会自动为其创建工具——这一机制在Common/Models/DatabaseModels下的事件、告警等模型中均有体现。自托管与开发无需单独部署MCP 服务器随 App 容器发布由 Nginx 在/mcp路径提供服务它调用的 OneUptime API URL 通过HOST与HTTP_PROTOCOL环境变量经Common/Server/EnvironmentConfig派生API 密钥永不配置在服务器端由客户端按请求提供开发与测试源码位于 App/FeatureSet/MCP启动时挂载进 App 服务测试位于App/FeatureSet/MCP/Tests可运行npx jest ./FeatureSet/MCP/Tests --runInBand执行。总结OneUptime MCP 服务器把监控、事件响应与可观测性能力以类型安全、无状态、可水平扩展的方式开放给了 AI 生态。通过一次简单的客户端配置Claude Desktop、VS Code Copilot 等工具即可获得对 OneUptime 实例的读写能力配合项目级最小权限密钥、readOnlyHint/destructiveHint安全注解与带内错误反馈可以在保障安全的前提下让 AI 代理真正参与日常监控与事件响应工作流。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime MCP 服务器接入指南：用 AI 助手驱动监控、事件响应与可观测性
OneUptime MCP 服务器接入指南用 AI 助手驱动监控、事件响应与可观测性【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读OneUptime 内置了基于 Model Context ProtocolMCP的 AI 接入层——MCP 服务器。它作为大型语言模型LLM与 OneUptime 实例之间的桥梁让 Claude、VS CodeGitHub Copilot等 MCP 兼容客户端通过约 155 个工具直接管理监控器、事件、告警、状态页、值班与遥测数据。本文基于 App/FeatureSet/Docs/Content/es/ai/mcp-server.md 与 App/FeatureSet/MCP 模块源码完整讲解其工作原理、配置方式、认证机制、工具清单与实战用法读完即可在自己的 Cloud 或自托管实例上接入并安全使用。什么是 OneUptime MCP 服务器MCP 服务器是 LLM 与 OneUptime 之间的桥接组件实现了 Model Context Protocol。它把 OneUptime 的监控与事件响应能力封装成一组可被 AI 代理直接调用的工具使 AI 助手能够以自然语言指令完成真实的运维操作。它的工作方式非常轻量托管在实例内服务器随 App 容器一同运行通过 Streamable HTTP 传输协议暴露在/mcp端点无需本地安装任何客户端组件云用户端点https://oneuptime.com/mcp自托管用户端点https://your-oneuptime-domain.com/mcp由 App 容器在 Nginx 之后提供无需单独部署。从源码看路由前缀在 App/FeatureSet/MCP/Config/ServerConfig.ts 中被定义为ROUTE_PREFIXES: string[] [/mcp]并在 App/Index.ts 中随MCPRoutes.init()挂载进 App 服务。核心特性约 155 个工具覆盖 22 种数据库资源类型的完整 CRUD 工具事件、告警、监控器、状态页、值班等加上只读遥测工具以及工作流与辅助工具实时操作对资源的创建、读取、更新、删除均可即时完成类型安全接口全部工具基于模型 Schema 生成带完备的输入校验安全认证按请求携带 API 密钥x-api-key头或 Bearer 令牌并妥善处理错误安全注解只读工具带readOnlyHint删除类工具带destructiveHintMCP 客户端可据此自动批准安全调用、对破坏性调用先征求确认易集成兼容 Claude Desktop 与其他 MCP 客户端无状态设计不发放会话 ID每次请求自包含可安全部署在负载均衡器与多副本环境之后。无状态设计是这套实现的关键。在 App/FeatureSet/MCP/Handlers/RouteHandler.ts 中每一次 POST 请求都会新建一个McpServer与StreamableHTTPServerTransport显式省略sessionIdGenerator请求处理完即销毁进程内不保留任何会话状态——因此多副本部署下连续请求落在不同 worker 上也能正常工作。正如该文件注释所述早期基于进程内内存 Map 的有状态实现在多副本部署如 oneuptime.com 本身时曾导致握手阶段出现 “404 MCP session not found” 故障。你能用 AI 做什么接入后AI 助手可以替你完成监控器管理创建与配置监控器、查看其状态、回溯状态历史事件响应创建、确认Acknowledge、解决事件添加内部/公开备注跟踪解决进度团队运维管理团队与值班策略On-Call Policy状态页管理状态页、发布公告Announcement告警确认与解决告警、添加告警备注、管理告警状态与严重级别计划维护创建与管理计划维护事件遥测查询日志、指标、链路Span、异常与监控器日志只读。前置要求一个 OneUptime 实例云版或自托管均可一个 MCP 兼容客户端Claude Desktop、VS Code GitHub Copilot 等有效的 OneUptime API 密钥仅认证操作需要公开工具无需密钥即可工作。获取 API 密钥登录 OneUptime 实例进入设置Settings→ API 密钥API Keys点击创建 API 密钥Create API Key填写名称例如MCP Server按实际用例选择适当的权限复制生成的密钥。密钥是项目级作用域的MCP 服务器从密钥推断项目归属因此所有创建类工具都不需要传projectId参数。这一点在 App/FeatureSet/MCP/Tools/WorkflowTools.ts 的oneuptime_whoami工具描述中也有明确说明。警告——永远不要把主密钥Master Key交给 AI 代理。OneUptime 的masterAPI 密钥也会被此请求头接受且拥有整个实例的管理员级访问权限。务必始终使用项目级、最小权限的 API 密钥只读密钥即可满足所有get_/list_/count_工具并在 App/FeatureSet/MCP/README.md 中再次强调同一安全约定。客户端配置配置 Claude DesktopClaude Desktop 的配置文件位置macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.jsonOneUptime Cloud 配置{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp, headers: { x-api-key: your-api-key-here } } } }自托管配置将oneuptime.com替换为你的 OneUptime 域名{ mcpServers: { oneuptime: { transport: streamable-http, url: https://your-oneuptime-domain.com/mcp, headers: { x-api-key: your-api-key-here } } } }公开访问不带密钥如果只想使用公开工具状态页信息、帮助等可以省略密钥{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp } } }该配置允许无需认证即可访问公开的状态页工具与帮助资源。VS Code GitHub CopilotVS Code 从 1.99 版本起原生支持 MCP 服务器使 Copilot 可以直接访问 OneUptime 数据。第 1 步前置条件VS Code 1.99 或更高版本已安装并启用的 GitHub Copilot 扩展已启用 GitHub Copilot Chat。第 2 步打开 MCP 配置按CtrlShiftPWindows/Linux或CmdShiftPmacOS输入 “MCP: Open User Configuration” 并回车这会打开或创建mcp.json配置文件。也可以在项目工作区创建.vscode/mcp.json实现项目级配置。Cloud 版配置{ 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 } ] }自托管版配置{ 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 步启动 MCP 服务器按CtrlShiftP/CmdShiftP输入 “MCP: List Servers” 查看可用服务器点击 “oneuptime” 启动服务器按提示输入你的 OneUptime API 密钥。第 4 步在 Copilot Chat 中使用打开 GitHub Copilot Chat使用代理模式workspace或直接提问What monitors do I have in OneUptime? Show me recent incidents Create a new monitor for https://example.com安全说明上述配置使用password: true的输入变量安全地提示你输入 API 密钥而不是以明文存储。首次启动 MCP 服务器时 VS Code 会要求信任确认。HTTP 端点一览端点方法说明/mcpPOSTJSON-RPC 请求用于工具调用及其他 MCP 操作/mcpGET无 SSEAccept头时返回友好的 JSON 发现负载带 SSE 头时返回405——无状态服务器不提供独立 SSE 流符合规范的客户端会继续工作/mcpDELETE无副作用无状态没有需要终止的会话/mcp/healthGET健康检查端点同时返回本构建支持的协议版本列表/mcp/toolsGETREST 接口列出全部可用工具这些端点的行为在 App/FeatureSet/MCP/Handlers/RouteHandler.ts 中逐一实现GET 无 SSE 时返回包含protocolVersions与latestProtocolVersion的发现负载健康检查则额外报告mode: stateless、工具数量与activeSessions: 0RouteHandler.ts。值得一提的协议兼容层由于真实世界的 MCP 客户端比 SDK 参考实现更严格也更宽松App/FeatureSet/MCP/Utils/TransportNegotiation.ts 会在请求进入 SDK 之前做两层协商——协议版本协商MCP-Protocol-Version请求头会被协商到双方都支持的最高版本比服务器更新的版本会被降级到服务器最新版本完全无法兼容的版本则返回400并列出支持版本清单而不是在传输层静默失败响应格式协商根据客户端的Accept头选择text/event-streamSSE或纯application/json响应体两者都是 MCP 规范中 POST 的合法答复若客户端两者都不接受则返回406。认证机制MCP 服务器支持两种运行模式公开工具无需认证不带 API 密钥也能连接服务器并使用公开工具oneuptime_help获取关于 OneUptime 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获取公开状态页公告。公开状态页工具接受状态页 IDUUID或状态页域名两种标识。在 App/FeatureSet/MCP/Tools/PublicStatusPageTools.ts 中输入会被严格校验为 UUID 或主机名格式防止路径穿越等构造值触达其他端点同时通过StatusPageService.isMcpServerEnabled检查状态页是否开放 MCP 访问PublicStatusPageTools.ts且“不存在”与“已禁用”返回同一错误信息避免被无密钥调用方枚举状态页。认证工具需要 API 密钥除公开工具外的所有操作监控器、事件、团队管理等都需要通过以下任一请求头认证x-api-key你的 OneUptime API 密钥Authorization带密钥的 Bearer 令牌例如Bearer your-api-key-here。Bearer方案不区分大小写RouteHandler.ts 中用/^Bearer\s(.)$/i匹配。密钥从请求头中即时读取extractApiKey服务器端不配置任何环境变量密钥每次请求自携带——这保证了多副本环境下的安全一致性。错误处理设计工具错误以带内工具结果返回isError: true携带statusCode、details和一条suggestion建议而不是作为 MCP 协议层错误抛出这样代理可以读取失败原因并自我修正。对应的底层异常类型OneUptimeApiError定义在 App/FeatureSet/MCP/Services/OneUptimeApiService.ts携带 HTTP 状态码与原始响应体。工作流工具除每个资源的 CRUD 工具外服务器还包含专门为事件与告警响应设计的工作流工具手写实现见 App/FeatureSet/MCP/Tools/WorkflowTools.tsacknowledge_incident/resolve_incident将事件移动到项目的“已确认”或“已解决”状态——等价于在控制台点击按钮acknowledge_alert/resolve_alert对告警执行同样操作add_incident_note为事件添加备注visibility: internal仅团队可见默认值或visibility: public发布到状态页。支持 Markdownadd_alert_note为告警添加内部备注。这些工具的底层实现非常巧妙源码注释说明解决一个事件本质上意味着创建一条指向项目 “Resolved” 状态的IncidentStateTimeline记录。changeState会先查询项目中isAcknowledgedState/isResolvedState为真的状态行再向/incident-state-timeline或/alert-state-timeline写入一条新记录WorkflowTools.ts——这与控制台按钮做的事完全一致从而让代理无需了解 OneUptime 内部数据模型即可正确操作。所有工作流工具对 ID 都做严格 UUID 校验ObjectID.isValidUUID。一个典型的事件响应闭环list_incidents→acknowledge_incident→ 用list_logs调查 →add_incident_note公开→resolve_incident身份确认oneuptime_whoamioneuptime_whoami返回你的 API 密钥所属的项目ID 与名称。它是代理用来定位自身上下文的最有用首发调用——由于创建类工具从密钥推断projectId代理永远不需要手动传入项目 ID。实现上它查询/api/project/get-list并返回projects数组WorkflowTools.ts。遥测查询只读日志、指标、链路spans、异常与监控器日志以只读的list_与count_工具暴露list_logs、list_metrics、list_spans、list_exception_instances、list_monitor_logs及其count_对应物。遥测数据通过 OpenTelemetry 摄入因此没有创建类工具——这是有意设计App/FeatureSet/MCP/README.md。务必使用时间范围过滤遥测查询。查询字段接受直接值或操作符对象{ 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。这些操作符语法同样会作为提示注入到每个查询参数的工具描述中帮助代理自行发现见 App/FeatureSet/MCP/Tools/ToolGenerator.ts。字段选择与分页get_与list_工具接受可选的select字段名数组。默认返回除重型字段JSON、超长文本、HTML 列外的全部可读字段重型字段需在select中显式请求。列表工具通过limit默认 10最大 100与skip分页常量定义于 App/FeatureSet/MCP/Config/ServerConfig.ts每次列表响应都会如实报告本次返回内容{ returnedCount: 10, totalCount: 42, skip: 0, limit: 10, hasMore: true, data: [...] }值得注意的一个实现细节当最小权限密钥无法读取默认 “all fields” select 中的某些列时OneUptime API 会拒绝整个请求。为此 App/FeatureSet/MCP/Services/OneUptimeApiService.ts 实现了自动降级重试解析出被拒列名、从 select 中删除该列后重试最多 10 次确保最小权限密钥依然能拿到结果。验证服务器状态# OneUptime Cloud curl https://oneuptime.com/mcp/health # 自托管 curl https://your-oneuptime-domain.com/mcp/health列出可用工具# OneUptime Cloud curl https://oneuptime.com/mcp/tools # 自托管 curl https://your-oneuptime-domain.com/mcp/tools实战示例以下自然语言指令可直接交给已接入的 AI 助手执行基础信息查询Whats the current status of all my monitors? Show me incidents from the last 24 hours监控器管理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 Assign the current payment gateway incident to the infrastructure team团队与值班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公开状态页查询无需密钥Whats 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? Get the latest announcements from my public status page with ID abc123-...进阶组合操作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 oneAPI 密钥权限管理只读访问仅查看数据时为密钥添加读取权限即可。完全访问如需创建、更新、删除资源的完全能力确保密钥拥有项目管理员权限。最佳实践最小权限只授予代理实际需要的最小权限定期轮换定期轮换 API 密钥监控用量在 OneUptime 中跟踪密钥使用情况环境隔离为不同环境使用不同密钥。另外从源码可见服务器端对最小权限密钥有很好的兼容性——包括上述 select 列权限降级重试以及带内错误返回都会引导最小权限代理自动规避无权限字段。故障排查权限错误确认 API 密钥具备所需权限列出资源需要读取权限创建/更新资源需要写入权限删除资源需要删除权限。连接问题确认 OneUptime 实例 URL 正确检查 API 密钥有效确保 OneUptime 实例可访问先测试健康检查端点。无效 API 密钥在 OneUptime 设置中核对密钥检查是否有多余空格或字符确认密钥未过期。会话相关错误如果遇到会话相关报错请记住MCP 服务器无状态——不发放也不跟踪会话 ID每次请求可命中任意副本从旧版本服务器带mcp-session-id头的客户端可以直接忽略该头服务器会忽略它更新期待服务器返回会话 ID 的旧 MCP 客户端配置。可用资源总览MCP 服务器为以下资源提供工具监控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监控器日志每个数据库资源通过 snake_case 命名支持 Create、Get、List、Update、Delete、Count 六种操作例如create_incident、get_incident、list_incidents、update_incident、delete_incident、count_incidents。遥测资源只暴露list_与count_工具如list_logs、count_spans。从工具生成机制看App/FeatureSet/MCP/Tools/ToolGenerator.ts 会扫描全部数据库模型与分析模型自动为每个启用的模型生成上述六类工具操作注解按类型自动分配——只读操作Read/List/Count加readOnlyHint更新操作加idempotentHint删除操作同时加destructiveHint与idempotentHintToolGenerator.ts。新模型接入 MCP 只需给数据库模型加上EnableMCP装饰器或为分析模型设置enableMCP下次启动时工具生成器便会自动为其创建工具——这一机制在Common/Models/DatabaseModels下的事件、告警等模型中均有体现。自托管与开发无需单独部署MCP 服务器随 App 容器发布由 Nginx 在/mcp路径提供服务它调用的 OneUptime API URL 通过HOST与HTTP_PROTOCOL环境变量经Common/Server/EnvironmentConfig派生API 密钥永不配置在服务器端由客户端按请求提供开发与测试源码位于 App/FeatureSet/MCP启动时挂载进 App 服务测试位于App/FeatureSet/MCP/Tests可运行npx jest ./FeatureSet/MCP/Tests --runInBand执行。总结OneUptime MCP 服务器把监控、事件响应与可观测性能力以类型安全、无状态、可水平扩展的方式开放给了 AI 生态。通过一次简单的客户端配置Claude Desktop、VS Code Copilot 等工具即可获得对 OneUptime 实例的读写能力配合项目级最小权限密钥、readOnlyHint/destructiveHint安全注解与带内错误反馈可以在保障安全的前提下让 AI 代理真正参与日常监控与事件响应工作流。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考