OneUptime MCP 实战：5 分钟接入与源码级设计解读

OneUptime MCP 实战5 分钟接入与源码级设计解读【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime MCP 把监控平台变成 AI 代理的 toolboxClaude 与 Copilot 用自然语言查遥测、处置事件、管状态页。读完你将能 3 分钟配好客户端打到/mcp能讲清无状态设计的三个关键决策能安全地给代理发最小权限密钥。 快速跑通3 分钟让 /mcp 有响应MCP 服务器随 App 容器一起托管无需本地安装云用户打https://oneuptime.com/mcp自托管用户在自己域名后拼/mcp由 Nginx 之后的 App 容器服务。拿到你的 OneUptime MCP API Key登录 → 项目设置Project Settings→ API Keys → 创建密钥按使用场景选权限。密钥是项目级作用域——服务端从密钥推断项目创建类工具永远不需要传projectId。在 Claude Desktop 配置中加入服务器自托管替换域名即可{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp, headers: { x-api-key: your-api-key-here } } } }一条命令验证端点存活curl https://your-oneuptime-domain.com/mcp/health响应带status: healthy、mode: stateless、工具数量、activeSessions: 0与该构建支持的协议版本列表。浏览器直接访问/mcp也会返回一份发现负载含协议版本握手失败时不用翻容器日志也能诊断。设计拆解为什么这样造OneUptime MCP 无状态设计不是审美选择每个决策都对应一次生产事故。无状态路由从 404 换来的教训问题早期版本把会话存在进程内内存 Map 里。多副本部署时initialize在 worker A 建会话下一个请求被负载均衡到 worker B整个握手报 404 MCP session not found。设计每次 POST 新建McpServer与 transport处理完即销毁永不签发mcp-session-id。这安全是因为tools/list来自路由初始化时绑定的工具列表tools/call用同一请求头里自带的密钥认证——每个请求自包含。源码佐证RouteHandler.ts 头部注释完整记录了该事故MCPServer.ts 的createMCPServerInstance()每次调用返回新实例。SDK 之前的协商让新客户端进来问题SDK 会拒绝任何它不认识的MCP-Protocol-Version或Accept头比 SDK 更新的客户端、或发通配Accept的客户端都会在传输层被拒错误只有容器日志里可见。设计请求进 SDK 前先协商——版本协商到双方共同的最高版并原地重写请求头完全对不上的版本返回 400 并附支持列表initialize请求丢弃不可用头、交给握手体协商响应格式按Accept选 JSON 或 SSE都不可接受时 406 并列明两种媒体类型。源码佐证TransportNegotiation.ts。按请求注入密钥避免全局竞态问题无状态多 worker 并发下进程级全局 API Key 存在竞态。设计密钥从本次请求头提取x-api-key或Authorization: Bearer keyscheme 不区分大小写registerToolHandlers()用闭包把它绑定到本次请求的工具处理器上。源码佐证ToolHandler.ts。 能力全景一张表看清约 155 个工具分类代表端点 / 工具资源范围MCP 主端点POST/GET/DELETE /mcpJSON-RPC 工具调用GET 不带 SSE 头返回发现负载、带则 405DELETE 为空操作诊断端点GET /mcp/health、GET /mcp/tools健康 协议版本列表REST 工具清单CRUD 工具每资源 6 个create_/get_/list_/update_/delete_/count_ 资源名22 个数据库资源Incident、Alert、Monitor、Status Page、On-Call Policy、Label 等遥测只读list_logs、count_spans等Log、Metric、Span、Exception Instance、Monitor Log工作流工具acknowledge_incident、add_incident_note等事件 / 告警的受理-解决闭环公共工具免密钥get_public_status_page_*、oneuptime_help公共状态页、帮助与资源清单全部约 155 个工具由 OneUptime 数据模型自动生成给模型加EnableMCP装饰器下次启动生成器即产出工具与输入 JSON Schema。遥测只有 list/count 两类——数据经 OpenTelemetry 摄取创建类工具没有意义。实战场景5 条指令跑通主链路只读查询— Show me incidents from the last 24 hours.list_incidentssort createdAt DESC小 limit配合count_incidentslist 默认返回 10、上限 100响应里的hasMore元数据会提示你用skip翻下一页。带时间范围的遥测— Find the top exceptions in the last hour.list_exception_instances加时间过滤——query 字段接受直接值或操作符对象GreaterThan、InBetween、Search等排序取ASC/DESC遥测表大limit 建议 10–50。写操作— Create a website monitor for https://example.com that checks every 5 minutes. 触发create_monitorprojectId 由密钥推断get_/list_还支持可选select数组默认响应排除 JSON、超长文本与 HTML 列重字段须显式点名。多步工作流— Acknowledge the newest incident, investigate with logs, post a customer update, then resolve it.list_incidents→acknowledge_incident→list_logs→add_incident_notevisibility: public会发到状态页→resolve_incident。工作流工具替你屏蔽了模型细节所谓解决实际是写入一条指向 Resolved 状态的IncidentStateTimeline等价于点仪表板按钮。免认证公共接口— Whats the current status of status.example.com?get_public_status_page_overview/_incidents接受状态页 UUID或域名oneuptime_whoami还能告诉你当前密钥属于哪个项目适合做代理的首个定位调用。客户端配置变体OneUptime MCP 配置按客户端分两种形态headers 里写静态密钥或用启动时提示输入的变量。自托管统一替换域名即可。在 VS Code Copilot 中挂载 OneUptimeVS Code 1.99 原生支持 MCP。mcp.json用户级或工作区.vscode/mcp.json用password: true的输入变量提示输入密钥避免明文落盘{ servers: { oneuptime: { type: http, url: https://oneuptime.com/mcp, headers: { x-api-key: ${input:oneuptime-api-key} } } }, inputs: [ { type: promptString, id: oneuptime-api-key, password: true } ] }注意首次启动会弹信任确认之后经 MCP: List Servers 启动 oneuptime 即可。Claude Code CLI 一条命令claude mcp add --transport http oneuptime https://oneuptime.com/mcp \ --header x-api-key: your-api-key-here注意密钥以明文写入 CLI 的本地配置共享仓库或团队机器上慎用。Cursor在项目里建.cursor/mcp.json{ mcpServers: { oneuptime: { url: https://oneuptime.com/mcp, headers: { x-api-key: your-api-key-here } } } }注意官方示例只写url与headers与 Claude Desktop 的transport字段写法不同照抄示例即可。公共免密钥模式只用公共状态页工具与帮助时整个 headers 省略{ mcpServers: { oneuptime: { transport: streamable-http, url: https://oneuptime.com/mcp } } }状态页所有者可在 Status Page → Advanced Settings → MCP Server 关闭单页 MCP 访问默认开启关闭后仅四个get_public_status_page_*工具对该页报错页面网站、RSS 与项目自身的认证工具不受影响。 安全与权限密钥与硬开关推荐最小权限只读密钥即可覆盖全部get_/list_/count_工具要建改资源再补写权限完整管理建议 Project Admin。留意密钥分级master 主密钥同样被该请求头接受、且带实例级管理员权限——推荐别把它交给代理用项目级密钥。服务端硬开关readOnlyHint/destructiveHint只是建议不少客户端会无差别自动批准非只读工具。想在服务端硬性裁剪工具面可设MCP_READ_ONLYtrue仅暴露 read/list/count或MCP_ALLOW_DESTRUCTIVEfalse移除全部 delete保留 create/update两者均接受true/1/yes见 ToolGenerator.ts 的实现。受限密钥读不到某些列时服务层会自动剔除该列并重试最小权限密钥仍能拿到结果。建议定期轮换密钥、不同环境分开用钥并在 OneUptime 中跟踪使用情况。 踩坑与排错症状404 MCP session not found → 定位旧版本服务器把会话存在单进程内存负载均衡落到别的副本 → 解法使用无状态构建它不签发会话 ID客户端带上旧mcp-session-id头可直接省略。症状400 报版本不支持 → 定位客户端MCP-Protocol-Version早于或不对应服务端任何已知版本 → 解法看GET /mcp/health的protocolVersions改发支持版本或干脆省略该头、交给 initialize 协商。症状406 Not Acceptable → 定位Accept头两种响应类型都不接受 → 解法发Accept: application/json或text/event-stream。症状工具结果isError: true且statusCode为 401/403 → 定位工具错误以带内结果返回附suggestion不是协议错误多为密钥无效或权限不足 → 解法到 Project Settings → API Keys 核对留意多余空格list 类工具只要读权限。症状免密钥连接后某个状态页的公共工具全部报错 → 定位该页所有者在 Advanced Settings → MCP Server 关闭了 MCP 访问 → 解法重新开启或改用认证工具get_status_page查询。延伸阅读packages/App/FeatureSet/Docs/Content/en/ai/mcp-server.md官方英文文档全文packages/App/FeatureSet/MCP/README.md模块 README 与测试跑法packages/App/FeatureSet/MCP/Tools/WorkflowTools.ts工作流工具实现【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考