企业官网建设流程全解析

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

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

OneUptime MCP 把监控平台变成 AI 代理的 toolbox：Claude 与 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 <key>，scheme 不区分大小写），registerToolHandlers()用闭包把它绑定到本次请求的工具处理器上。
• 源码佐证：ToolHandler.ts。

🧭 能力全景：一张表看清约 155 个工具

全部约 155 个工具由 OneUptime 数据模型自动生成：给模型加@EnableMCP装饰器，下次启动生成器即产出工具与输入 JSON Schema。遥测只有 list/count 两类——数据经 OpenTelemetry 摄取，创建类工具没有意义。

实战场景：5 条指令跑通主链路

1. 只读查询— "Show me incidents from the last 24 hours."list_incidents（sort createdAt DESC，小 limit）配合count_incidents；list 默认返回 10、上限 100，响应里的hasMore元数据会提示你用skip翻下一页。
2. 带时间范围的遥测— "Find the top exceptions in the last hour."list_exception_instances加时间过滤——query 字段接受直接值或操作符对象（GreaterThan、InBetween、Search等），排序取ASC/DESC；遥测表大，limit 建议 10–50。
3. 写操作— "Create a website monitor for https://example.com that checks every 5 minutes." 触发create_monitor，projectId 由密钥推断；get_/list_还支持可选select数组，默认响应排除 JSON、超长文本与 HTML 列，重字段须显式点名。
4. 多步工作流— "Acknowledge the newest incident, investigate with logs, post a customer update, then resolve it."list_incidents→acknowledge_incident→list_logs→add_incident_note（visibility: "public"会发到状态页）→resolve_incident。工作流工具替你屏蔽了模型细节：所谓"解决"实际是写入一条指向 Resolved 状态的IncidentStateTimeline，等价于点仪表板按钮。
5. 免认证公共接口— "What's the current status of status.example.com?"get_public_status_page_overview/_incidents接受状态页 UUID或域名；oneuptime_whoami还能告诉你当前密钥属于哪个项目，适合做代理的首个定位调用。

客户端配置变体

OneUptime MCP 配置按客户端分两种形态：headers 里写静态密钥，或用启动时提示输入的变量。自托管统一替换域名即可。

在 VS Code + Copilot 中挂载 OneUptime

VS 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_ONLY=true（仅暴露 read/list/count）或MCP_ALLOW_DESTRUCTIVE=false（移除全部 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