OneUptime

OneUptime MCP 服务

一种 Model Context Protocol（MCP）服务，可向 AI Agent 提供 OneUptime 功能。它让兼容 MCP 的客户端（Claude、集成 Copilot 的 VS Code、Cursor 等）通过约 190 个工具管理事件、告警、监控器、状态页、值班和遥测数据。

工作原理

• 传输方式：通过 /mcp 使用 Streamable HTTP。该服务是无状态的——不会颁发或要求会话 ID，因此可安全地部署在负载均衡器之后，或采用多副本部署。
• 托管端点：https://oneuptime.com/mcp
• 自托管端点：https://<your-host>/mcp（由 Nginx 后方的 App 容器提供）
• 身份验证：登录 OneUptime（使用 MCP 授权规范规定的 OAuth 2.1），或在每个请求中通过 x-api-key 请求头或 Authorization: Bearer <key> 提供 API 密钥（方案不区分大小写）。不支持通过环境变量提供 API 密钥——每个请求都必须携带自己的凭据。

连接客户端

通过登录连接

只需向客户端提供 URL，无需其他内容。首次调用需要身份凭据的工具时，服务会返回 401 和 WWW-Authenticate 质询；客户端会据此发现授权服务器，在用户的浏览器中打开授权同意页面，并获取用户所选项目的令牌。

claude mcp add --transport http oneuptime https://oneuptime.com/mcp

{ "servers": { "oneuptime": { "type": "http", "url": "https://oneuptime.com/mcp" } } }

本节其余内容介绍如何使用 API 密钥配置相同的客户端，适用于无人值守运行的 Agent。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "oneuptime": {
      "transport": "streamable-http",
      "url": "https://oneuptime.com/mcp",
      "headers": {
        "x-api-key": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http oneuptime https://oneuptime.com/mcp \
  --header "x-api-key: your-api-key-here"

VS Code（GitHub Copilot）

.vscode/mcp.json 或用户 MCP 配置：

{
  "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
    }
  ]
}

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "oneuptime": {
      "url": "https://oneuptime.com/mcp",
      "headers": {
        "x-api-key": "your-api-key-here"
      }
    }
  }
}

对于自托管实例，请将上述任意配置中的 oneuptime.com 替换为你的 OneUptime 主机地址。

身份验证

API 密钥

在 OneUptime 中，通过 Project Settings → Advanced → API Keys 创建一个项目 API 密钥，并授予 Agent 所需的最低权限（只读密钥可用于所有 get_/list_/count_ 工具）。项目会根据密钥推断，因此创建类工具无需 projectId 参数。

警告——切勿向 AI Agent 提供主密钥。 OneUptime 的 master API 密钥也可通过此请求头使用，并授予实例范围的管理员访问权限。务必为 AI Agent 使用遵循最小权限原则的项目级 API 密钥。

公共状态页工具以及 oneuptime_help / oneuptime_list_resources 无需任何凭据即可使用。

OAuth 登录

代码位于 OAuth/；每个文件开头都说明了背后的设计思路。整体设计如下：

• /mcp 下只有一个发行者。 https://<host>/mcp 同时是受保护资源（RFC 9728）和授权服务器的发行者（RFC 8414）。所有端点都位于 /mcp/oauth 下，所有 URL 均根据 HOST / HTTP_PROTOCOL 构建，绝不使用请求中的信息。
• 在 HTTP 层延迟处理。 OAuth/RequestGate 在 MCP SDK 收到请求之前运行。initialize、tools/list 和公开工具无需凭据即可通过；调用需要身份的工具时，会返回 401（只读授权调用写入工具时返回 403 insufficient_scope），并附带 Bearer 挑战。此逻辑不能放在工具处理程序中：SDK 内部的拒绝响应是 200，只有收到真正的 401，客户端才会开始为用户发起登录流程。
• 客户端需表明自身身份。 可以使用客户端 ID 元数据文档（OAuth/ClientIdMetadataDocument，通过出口防护机制获取，始终屏蔽私有地址），也可以使用动态客户端注册（OAuth/RegistrationEndpoint）。无需手动注册客户端。
• 授权码 + PKCE（仅支持 S256）、资源指示符（RFC 8707）、授权响应中的 iss（RFC 9207）、带重用检测的刷新令牌轮换、令牌撤销（RFC 7009）。
• 不透明令牌，以哈希形式存储。 oumcp_ac_… / oumcp_at_… / oumcp_rt_…；只保存 SHA-256（McpOAuthToken）。授权（McpOAuthGrant）表示一个成员允许一个客户端在一个项目中代表自己执行操作；撤销授权即删除该授权，并级联删除其令牌。
• 只有访问令牌才是凭据。 x-api-key 仅承载 API 密钥；Authorization 承载 API 密钥或访问令牌。无论在哪个请求头中，只要出现其他 oumcp_ 密钥（刷新令牌、授权码、客户端密钥，或出现在 x-api-key 中的访问令牌），OAuth/RequestGate 都会以 401 invalid_token 拒绝，绝不会将其作为 API 密钥传给 API。
• 作用域 mcp:read 和 mcp:write（写入包含读取权限）。同意页面可以缩小客户端请求的权限范围，但不能扩大。
• API 不会看到客户端的令牌。 MCP 层接受访问令牌后，会使用有效期为 60 秒的签名委派令牌（Common/Server/Utils/Mcp/McpDelegationToken）调用 REST API。Common/Server/Middleware/McpDelegationAuthorization 会将其转换为以成员身份而非主管理员身份发起的请求；请求限定在授权所属项目内，使用成员当前权限，并在授权为只读时标记为只读。因此，访问令牌被盗后，其价值恰好等同于 MCP 工具可执行操作的权限。
• 每次使用时都会检查。 Common/Server/Utils/Mcp/McpOAuthGrantAccess 会在每次请求和每次令牌交换时重新评估授权：成员仍然存在、未被封禁、仍属于该项目、不在会阻止 AuthorizeMcpClient 的团队中，并且仍符合项目的 SSO 要求。
• 同意页面位于账户页面 /accounts/mcp-authorize；管理已连接的客户端位于控制面板的 Settings → MCP Server。

有两个设置项：DISABLE_MCP_OAUTH=true 会关闭整个功能（路由返回 404，未认证的工具调用则返回原有的带内结果“API key is required”）；DISABLE_MCP_OAUTH_CLIENT_ID_METADATA_DOCUMENTS=true 适用于无法向外发起请求的实例。

工具目录

数据库资源 — 完整 CRUD

以下 27 个模型各提供六种工具：create_、get_、list_、update_、delete_、count_（例如：create_incident、get_incident、list_incidents、update_incident、delete_incident、count_incidents）：

Incident、Alert、Incident Alert、Monitor、Status Page、Scheduled Maintenance Event、Team、Monitor Status、On-Call Policy、Incident State、Incident Severity、Alert State、Alert Severity、Incident State Timeline、Alert State Timeline、Incident Public Note、Incident Internal Note、Alert Internal Note、Status Page Announcement、Scheduled Maintenance State、Scheduled Maintenance State Timeline、Label、Monitor Status Event、Security Case、Security Case Note、Security Detection、Security Playbook。

遥测资源 — 只读

Log、Metric、Span、Exception Instance、Monitor Log、Security Event、Change Event、Kubernetes Cost Allocation 和 Threat Intel Indicator 仅提供 list_ 和 count_ 工具（例如：list_logs、count_spans、list_exception_instances）。遥测数据没有创建工具——数据通过 OpenTelemetry 摄取。

工作流工具

专为事件／告警响应设计的快捷工具（packages/App/FeatureSet/MCP/Tools/WorkflowTools.ts）：

• acknowledge_incident、resolve_incident
• acknowledge_alert、resolve_alert
• add_incident_note（通过 visibility: "internal" | "public" 设置可见性；公开备注会发布到状态页）
• add_alert_note
• oneuptime_whoami — 返回凭据所属的项目（ID 和名称）；如果通过 OAuth 登录，还会返回登录用户、所用客户端，以及连接是否为只读

辅助工具和公开工具

• 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

注解和结果

每个工具都有标题，并设置全部三种 MCP 提示，配置位于 Tools/ToolAnnotations.ts，以便客户端自动批准安全调用，并确认其他调用：

• 对不产生任何更改的工具设置 readOnlyHint: true：get_、list_、count_、oneuptime_whoami、辅助工具和公开状态页工具。
• 对所有会产生更改的工具设置 destructiveHint: true：创建、更新和删除工具，确认和解决操作，以及添加备注。大多数写入操作会覆盖或删除记录、更改事件或告警的状态、呼叫值班人员，或向状态页发布内容；目录仅允许对不会发送任何内容的新增写入设置 false。
• 仅对公开状态页工具设置 openWorldHint: true，因为这些工具会读取此实例上的任意公开状态页。其他所有工具的操作范围都限制在调用者的项目内。

MCP 目录要求设置这些注解：Claude Connectors Directory 会标记任何缺少 title 或 readOnlyHint／destructiveHint 的工具，而 ChatGPT 的目录要求将全部三种提示设为布尔值。Tests/ToolAnnotationsForDirectories.test.ts 会在工具缺少任意一项注解或违反上述规则时失败。在服务端，MCP_ALLOW_DESTRUCTIVE=false 仅会移除删除工具，而 MCP_READ_ONLY=true 会移除所有非只读工具（Tests/WritePolicy.test.ts）。工具结果除 JSON 文本外还包含 structuredContent。错误会以内联工具结果的形式返回（isError: true），并包含 statusCode、details 和 suggestion，而不是作为协议错误返回。

查询、排序、选择和分页

查询

查询字段可接受直接值或运算符对象：

{
  "query": {
    "title": { "_type": "Search", "value": "database" },
    "createdAt": { "_type": "GreaterThan", "value": "2026-07-01T00:00:00.000Z" }
  }
}

运算符：EqualTo、NotEqual、IsNull、NotNull、EqualToOrNull、GreaterThan、LessThan、GreaterThanOrEqual、LessThanOrEqual、InBetween、Search、Includes。

排序

{ "sort": { "createdAt": "DESC" } }

值为 "ASC" 或 "DESC"。

选择

get_ 和 list_ 工具接受可选的 select 字段名数组。默认返回所有可读字段，但不包括较大的字段（JSON／VeryLongText／HTML 列），如需这些字段，必须显式请求。

分页

limit 默认为 10（最大值为 100）；skip 用于偏移结果集。列表响应会返回完整的请求页面，并提供准确的分页元数据：

{
  "returnedCount": 10,
  "totalCount": 42,
  "skip": 0,
  "limit": 10,
  "hasMore": true,
  "data": ["..."]
}

示例工作流

Agent 可执行的典型事件响应流程：

1. oneuptime_whoami — 确认凭据所属的项目。
2. 使用 {"sort": {"createdAt": "DESC"}, "limit": 5} 调用 list_incidents — 查找当前事件。
3. acknowledge_incident — 接手处理。
4. 使用时间范围筛选条件（{"time": {"_type": "GreaterThan", "value": "..."}}）调用 list_logs，并调用 list_exception_instances — 调查问题。
5. 使用 "visibility": "public" 调用 add_incident_note — 向客户发布状态更新。
6. resolve_incident — 解决并关闭事件。

HTTP 端点

端点	方法	行为
/mcp	POST	JSON-RPC（工具调用和所有 MCP 操作）
/mcp	GET	没有 SSE Accept 标头时：返回友好的 JSON 发现信息。有 SSE Accept 标头时：返回 405（无状态模式下不提供独立的 SSE 流）。
/mcp	DELETE	不执行任何操作（无状态 — 无需终止任何内容）
/mcp/tools	GET	以 REST 形式列出可用工具
/mcp/health	GET	健康检查，包括此构建支持的协议版本
/mcp/.well-known/oauth-protected-resource	GET	受保护资源元数据（也可通过 /.well-known/oauth-protected-resource[/mcp] 访问）
/.well-known/oauth-authorization-server/mcp	GET	授权服务器元数据（也可通过 /mcp/.well-known/oauth-authorization-server 和源站根路径访问）
/mcp/oauth/authorize	GET, POST	授权端点：检查客户端请求并重定向到同意页面
/mcp/oauth/token	POST	交换授权码和刷新令牌
/mcp/oauth/register	POST	动态客户端注册
/mcp/oauth/revoke	POST	撤销令牌
/mcp/oauth/consent/{details,approve,deny}	POST	同意页面自身的调用（仅限同源，使用会话 Cookie）

协议兼容性

服务端会协商，而不是拒绝，因此客户端无需与 App 容器中捆绑的 MCP SDK 完全匹配。

协议版本。 MCP-Protocol-Version 请求头会协商为双方都支持的最高版本。重复发送的请求头会读取其第一个值——Node 会将重复请求头合并为一个逗号分隔的字符串，而版本号中不会包含逗号：

• 如果版本受服务端支持，则按原样使用；
• 如果版本比服务端所知的所有版本都新（例如，客户端使用的是规范更新修订版），则协商降级到服务端的最新版本——与 initialize 给出的结果相同；
• 如果版本比服务端支持的所有版本都旧，或者根本不是 YYYY-MM-DD 格式的版本号，则双方没有共同版本。请求会收到 400 响应和一条 JSON-RPC 错误，其中会指出请求的版本并列出支持的版本，而不是在传输层静默失败。

对于 initialize 请求，不可用的请求头会被丢弃而非拒绝，因为该请求会通过请求体协商版本。存在但为空白的请求头也会被丢弃：对 SDK 来说，空字符串不同于缺少请求头，否则它会像拒绝其他未知版本一样拒绝该请求头。

GET /mcp 和 GET /mcp/health 都会列出支持的版本，因此无需查看容器日志即可诊断握手失败。

响应格式。 POST 请求会根据客户端 Accept 请求头允许的格式作出响应：客户端按名称或通过 text/* 范围请求时，返回 text/event-stream（符合规范的 MCP 客户端会这样请求）；否则返回普通的 application/json 响应体——包括 Accept: application/json、application/* 或 */* 通配符，以及完全没有 Accept 请求头的情况。根据 MCP 规范，以上两种格式都可用于响应 POST 请求。如果客户端两种格式都不接受，则会收到 406，其中会列出端点可生成的媒体类型。

诊断信息。 协商日志描述的是客户端：日志根据重写请求头之前获取的快照生成，因此记录的是实际发送的值，而不是此服务端规范化后的值。日志中的每个字段——包括请求头值和 JSON-RPC 方法——都会去除控制字符并限制长度，因此调用方无法伪造日志行或通过这些字段灌满日志。API 密钥或访问令牌绝不会被记录。

自托管

MCP 服务作为 App 容器的一部分提供，并通过 Nginx 在 /mcp 路径上提供服务——无需单独部署。其工具会通过 App 内部地址 SERVER_APP_HOSTNAME 和 APP_PORT 调用 OneUptime API，也就是 Nginx 代理 /api 所使用的地址（继承自 App 服务的环境）——绝不会通过公共 HOST 调用，因为 App 容器不一定能访问该地址（当 HOST=localhost 时，它指的是容器本身）。服务端不会配置 API 密钥；客户端会在每个请求中提供密钥。

OAuth 登录也无需任何配置，但依赖于 HOST 和 HTTP_PROTOCOL 必须对应用户实际使用的地址：颁发者、令牌受众以及发现文档中的每个端点都会根据它们构建。OneUptime 前方的反向代理必须将 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server（及其下的所有内容）与 /mcp 一起转发到 App；捆绑的 Nginx 已处理此事。

MCP 注册表

OneUptime Cloud 的服务已列入官方 MCP 注册表，MCP 客户端和目录会读取该注册表；其标识为 com.oneuptime/mcp。server.json 是对应条目：它通过 https://oneuptime.com/mcp 提供可流式传输的 HTTP，使用 OAuth 登录，也可在可选的 x-api-key 标头中提供项目 API 密钥。其 version 是占位符 0.0.0。

每次发布都会以对应的版本号发布该条目。GitHub release 发布后，.github/workflows/release.yml 中的 publish-mcp-registry 作业会运行 Scripts/MCP/PublishToMcpRegistry.sh，并跳过注册表中已有的版本，因此重新运行发布流程不会重复发布。已发布的版本无法更改。

只有控制 oneuptime.com 的人才能以 com.oneuptime 名义发布。该作业使用 Ed25519 私钥登录，其公钥需添加到 oneuptime.com 的 TXT 记录中；两者未就绪时，作业会失败且不会发布任何内容。设置方法如下（Ed25519 需要 OpenSSL 3；在 macOS 上，运行 brew install openssl@3 并使用其中的 openssl，而不是系统自带的 LibreSSL）：

1. 生成密钥对：

   openssl genpkey -algorithm Ed25519 -out mcp-registry-key.pem
   

2. 在 oneuptime.com 本身（而非 _mcp.oneuptime.com 等子域名）添加 TXT 记录，记录值为以下命令输出的内容：

   echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in mcp-registry-key.pem -pubout -outform DER | tail -c 32 | base64)"
   

3. 在仓库的 Settings → Environments 中创建 mcp-registry-publish，将部署分支限制为 release，并添加密钥 MCP_REGISTRY_PRIVATE_KEY：其值为以下命令输出的十六进制私钥：

   openssl pkey -in mcp-registry-key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'
   

然后删除 mcp-registry-key.pem，或将其妥善保管：持有该密钥的人可以发布并覆盖 com.oneuptime 下的任何条目。更换密钥时，同时替换 TXT 记录和密钥；如果新记录旁还留有旧记录，系统会先尝试旧记录，导致登录失败。

如需在下次发布前提前发布，请在仓库根目录手动运行脚本，并确保已安装 mcp-publisher 和 jq：PACKAGE_VERSION=<version> MCP_REGISTRY_PRIVATE_KEY=<hex key> bash Scripts/MCP/PublishToMcpRegistry.sh。

ChatGPT 插件目录

ChatGPTPlugin/ 是 OneUptime 上传到 ChatGPT 插件目录的程序包，ChatGPT 和 Codex 共用此目录：其中包括插件条目、五个正面和三个负面审核测试用例，以及指向 https://oneuptime.com/mcp 并通过 OAuth 登录以获取读写权限的 mcp.json。运行 npm run build-chatgpt-plugin 可构建 ZIP 文件。其 README 列出了提交所需的其他内容：经过验证的开发者身份、通过 https://oneuptime.com/.well-known/openai-apps-challenge 提供的域名验证令牌、演示项目的审核者凭据，以及演示视频。Tests/ChatGPTPlugin.test.ts 会验证程序包是否符合 Agent Plugins 架构和 OpenAI 的限制，并检查每个测试用例中提到的工具是否都由此服务提供。

开发

MCP 服务位于 packages/App/FeatureSet/MCP，并在启动时挂载到 App 服务中（packages/App/Index.ts）。测试位于 packages/App/FeatureSet/MCP/Tests，并作为 App 测试套件的一部分运行：

cd packages/App
npm install
npx jest ./FeatureSet/MCP/Tests --runInBand

系统会自动识别新模型：在数据库模型上添加 @EnableMCP 装饰器（或在分析模型上设置 enableMCP），工具生成器便会在下次启动时创建相应工具。

许可证

Apache-2.0——详情请参阅 LICENSE 文件。