On-Call Health

oncallhealth-mcp

用于 On-Call Health 值班倦怠分析的 MCP 服务。将 AI 助手连接到您的值班数据，以洞察工作负载。

前提条件

• 拥有 oncallhealth.ai 的 On-Call Health 账户
• 从 oncallhealth.ai/settings/api-keys 获取 API 密钥

安装

此服务通过 uvx 在本地使用 stdio 运行（无需安装），并从 ONCALLHEALTH_API_KEY 环境变量读取 API 密钥。请选择您的客户端：

Claude Code

claude mcp add oncallhealth --env ONCALLHEALTH_API_KEY=och_live_... -- uvx oncallhealth-mcp

Claude Desktop

添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "oncallhealth": {
      "command": "uvx",
      "args": ["oncallhealth-mcp"],
      "env": { "ONCALLHEALTH_API_KEY": "och_live_your_api_key_here" }
    }
  }
}

Cursor

添加到项目中的 .cursor/mcp.json（或全局配置 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "oncallhealth": {
      "command": "uvx",
      "args": ["oncallhealth-mcp"],
      "env": { "ONCALLHEALTH_API_KEY": "och_live_your_api_key_here" }
    }
  }
}

VS Code / GitHub Copilot

添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "oncallhealth": {
      "command": "uvx",
      "args": ["oncallhealth-mcp"],
      "env": { "ONCALLHEALTH_API_KEY": "och_live_your_api_key_here" }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "oncallhealth": {
      "command": "uvx",
      "args": ["oncallhealth-mcp"],
      "env": { "ONCALLHEALTH_API_KEY": "och_live_your_api_key_here" }
    }
  }
}

Codex CLI

codex mcp add oncallhealth --env ONCALLHEALTH_API_KEY=och_live_... -- uvx oncallhealth-mcp

Gemini CLI

gemini mcp add oncallhealth -e ONCALLHEALTH_API_KEY=och_live_... uvx oncallhealth-mcp

手动配置 / 其他客户端

pip install oncallhealth-mcp
export ONCALLHEALTH_API_KEY=och_live_...
oncallhealth-mcp

也可以不安装直接运行：ONCALLHEALTH_API_KEY=och_live_... uvx oncallhealth-mcp。

配置

变量	必填	默认值	描述
ONCALLHEALTH_API_KEY	是（stdio）	-	来自 oncallhealth.ai 的 API 密钥
ONCALLHEALTH_API_URL	否	https://api.oncallhealth.ai	API 端点 URL
ONCALLHEALTH_CODE_MODE	否	off	1 会通过 Code Mode 元工具公开目录（见下文）
ONCALLHEALTH_POLL_INTERVAL	否	5.0	analysis_run 内两次状态检查之间的秒数（间隔会逐渐延长，最大为 ONCALLHEALTH_POLL_MAX_INTERVAL，默认值为 30.0）
ONCALLHEALTH_MCP_ALLOWED_HOSTS	否	-	仅适用于 HTTP：启用 Host/Origin DNS 重绑定防护的逗号分隔主机名

请求超时、重试和断路器设置也可配置；请参阅 oncallhealth_mcp/client/config.py。

安全说明

避免将 API 密钥提交到版本控制中。请使用环境变量或密钥管理器，不要在配置文件中硬编码密钥。

协议兼容性

此服务实现 MCP 修订版本 2026-07-28（无状态 Streamable HTTP、Mcp-Method/Mcp-Name 路由标头、可缓存的列表结果、Tasks 扩展），并会按连接协商较旧的修订版本，因此使用 2025 握手时期协议的客户端仍可正常工作。每个工具都会发布注释（只读、幂等、开放世界）和结构化输出架构。此服务不提供已弃用的 HTTP+SSE 传输方式。

工具

先运行 validate_integrations，然后运行 analysis_current（或在需要重新分析时运行 analysis_run），接着运行 analysis_summary 和成员级工具。

工具	功能
validate_integrations	检查每个已连接的集成是否具有有效凭据。force_refresh 可绕过后端缓存。
integrations_list	列出已连接的 Rootly、GitHub、Slack、Jira 和 Linear 集成。
oncall_users	查询 Rootly 集成（integration_id）当前值班的人员。
analysis_current	最新分析的元数据（状态、时间戳、配置）。
analysis_run	启动分析并等待完成：days_back（默认 30）、include_weekends、integration_id、wait_timeout_seconds（默认 600）。返回团队摘要。对于支持 MCP Tasks 扩展的客户端，以后台任务方式运行；否则内联运行，并在等待期间发送进度消息。
analysis_start	启动分析但不等待。使用 analysis_status 轮询。
analysis_status	分析（analysis_id）的状态和元数据。
analysis_summary	团队平均值、风险分布、风险最高的五位成员和健康状况最好的成员。
analysis_results	已完成分析的完整原始数据（内容较多，建议优先使用专用工具）。
get_at_risk_users	风险评分达到或超过 min_och_score（默认 50），且风险级别属于 include_risk_levels（默认 ["medium", "high"]）的成员，并提供其 Rootly/PagerDuty/Slack/GitHub ID。
get_safe_responders	风险评分不高于 max_och_score（默认 30）的成员，可承担额外班次；最多返回 limit 位。
check_users_risk	检查指定 rootly_user_ids（整数列表）的风险，并分为有风险、健康和未找到三类。
member_daily_health	按天查看 member_email 的健康状况、事件和非工作时间情况。

OCH 评分范围为 0-100；分数越高，风险越大。评分可用于排班决策，但不能作为医疗诊断。

资源

URI	内容
oncallhealth://methodology	评分方法的简要说明
oncallhealth://analyses/latest	最新分析的元数据（JSON）
oncallhealth://analyses/{analysis_id}/summary	已完成分析的团队摘要（JSON）

提示词

提示词	参数	用途
weekly_brief	team_name	每周值班健康简报及后续行动
investigate_responder	member_email、analysis_id	深入分析一位响应人员的趋势，并建议调整班次

代码模式（可选）

使用 --code-mode 或 ONCALLHEALTH_CODE_MODE=1 时，目录会通过 FastMCP Code Mode 暴露：三个元工具（search、get_schema、execute）让 Agent 按需发现工具，并在沙盒化的 Python 代码片段中串联调用。当 Agent 每项任务需要进行多次调用时，这种方式可以节省上下文；代价是客户端无法直接读取工具列表、注释和输出架构。默认关闭。

CLI 参考

usage: oncallhealth-mcp [-h] [--transport {stdio,http}] [--host HOST]
                        [--port PORT] [--code-mode] [-v] [--version]

options:
  --transport {stdio,http}  Transport to use (default: stdio)
  --host HOST               Host to bind to (http transport only, default: 127.0.0.1)
  --port PORT               Port to bind to (http transport only, default: 8000)
  --code-mode               Expose the catalog through Code Mode meta-tools
  -v, --verbose             Enable verbose logging
  --version                 show program's version number and exit

托管部署（Streamable HTTP）

oncallhealth-mcp --transport http（或运行 uvicorn oncallhealth_mcp.transport:mcp_http_app 的 Docker 镜像）提供：

• POST /mcp：无状态 Streamable HTTP MCP 端点
• GET /health：无需身份验证的健康检查

每个 MCP 请求都必须在 Authorization: Bearer och_... 中携带用户的 API 密钥；也接受 X-API-Key: och_...。密钥会通过 On-Call Health API 验证（验证成功的结果会缓存五分钟），未经身份验证的请求会在任何工具运行之前收到 401。工具调用会按密钥和工具进行速率限制（例如，analysis_run 和 analysis_start 每分钟 5 次），限制依据 JSON-RPC 请求体识别；超出限制时会返回 429 和 Retry-After。

远程客户端配置示例（Claude Code）：

claude mcp add --transport http oncallhealth https://your-host/mcp --header "Authorization: Bearer och_live_..."

由于服务是无状态的，你可以运行多个 uvicorn 工作进程或副本。若要让 analysis_run 后台任务在多个工作进程间共享，请通过 FASTMCP_DOCKET_URL 将 FastMCP 的任务后端指向 Redis 或 Valkey；默认的内存后端仅限单个进程。

设置 ONCALLHEALTH_MCP_ALLOWED_HOSTS=mcp.example.com，即可为公共主机名启用 FastMCP 的 Host/Origin DNS 重绑定防护。

docker build -t oncallhealth-mcp .
docker run -p 8080:8080 oncallhealth-mcp

链接

• On-Call Health - 官方网站
• API 文档 - REST API 文档
• GitHub Issues - 报告错误

许可证

Apache-2.0