On-Call Health

oncallhealth-mcp

MCP server for On-Call Health burnout analysis. Connects AI assistants to your on-call data for workload insights.

Prerequisites

• An On-Call Health account at oncallhealth.ai
• An API key from oncallhealth.ai/settings/api-keys

Installation

The server runs locally over stdio with uvx (no install step) and reads the API key from the ONCALLHEALTH_API_KEY environment variable. Pick your client:

Claude Code

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

Claude Desktop

Add to 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

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

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

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project:

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

Windsurf

Add to ~/.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

Manual / other clients

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

Or run without installing: ONCALLHEALTH_API_KEY=och_live_... uvx oncallhealth-mcp.

Configuration

Variable	Required	Default	Description
ONCALLHEALTH_API_KEY	Yes (stdio)	-	API key from oncallhealth.ai
ONCALLHEALTH_API_URL	No	https://api.oncallhealth.ai	API endpoint URL
ONCALLHEALTH_CODE_MODE	No	off	1 exposes the catalog through Code Mode meta-tools (see below)
ONCALLHEALTH_POLL_INTERVAL	No	5.0	Seconds between status checks inside analysis_run (backs off to ONCALLHEALTH_POLL_MAX_INTERVAL, default 30.0)
ONCALLHEALTH_MCP_ALLOWED_HOSTS	No	-	HTTP only: comma-separated host names that enable the Host/Origin DNS-rebinding guard

Request timeouts, retries and circuit-breaker settings are also configurable; see oncallhealth_mcp/client/config.py.

Security note

Avoid committing API keys to version control. Use environment variables or a secrets manager instead of hardcoding keys in config files.

Protocol compatibility

The server implements MCP revision 2026-07-28 (stateless Streamable HTTP, Mcp-Method/Mcp-Name routing headers, cacheable list results, the Tasks extension) and negotiates older revisions per connection, so clients on the 2025 handshake-era protocol keep working. Every tool publishes annotations (read-only, idempotent, open-world) and a structured output schema. The deprecated HTTP+SSE transport is not served.

Tools

Start with validate_integrations, then analysis_current (or analysis_run for a fresh analysis), then analysis_summary and the member-level tools.

Tool	What it does
validate_integrations	Check that every connected integration has valid credentials. force_refresh bypasses the backend cache.
integrations_list	List connected Rootly, GitHub, Slack, Jira and Linear integrations.
oncall_users	Who is currently on call for a Rootly integration (integration_id).
analysis_current	Metadata of the most recent analysis (status, timestamps, config).
analysis_run	Start an analysis and wait for it: days_back (default 30), include_weekends, integration_id, wait_timeout_seconds (default 600). Returns the team summary. Runs as a background task for clients that support the MCP Tasks extension, inline otherwise, with progress messages while waiting.
analysis_start	Start an analysis without waiting. Poll with analysis_status.
analysis_status	Status and metadata of an analysis (analysis_id).
analysis_summary	Team averages, risk distribution, top five at-risk and healthiest members.
analysis_results	Full raw payload of a completed analysis (large; prefer the focused tools).
get_at_risk_users	Members at or above min_och_score (default 50) in include_risk_levels (default ["medium", "high"]), with Rootly/PagerDuty/Slack/GitHub IDs.
get_safe_responders	Members at or below max_och_score (default 30) who could take extra shifts, up to limit.
check_users_risk	Risk check for specific rootly_user_ids (list of integers), split into at-risk, healthy and not-found.
member_daily_health	Day-by-day health, incident and after-hours breakdown for member_email.

OCH scores run 0-100; higher means more at risk. Scores inform staffing decisions and are not a medical diagnosis.

Resources

URI	Content
oncallhealth://methodology	Short description of the scoring methodology
oncallhealth://analyses/latest	Metadata of the most recent analysis (JSON)
oncallhealth://analyses/{analysis_id}/summary	Team summary of a completed analysis (JSON)

Prompts

Prompt	Arguments	Purpose
weekly_brief	team_name	Weekly on-call health brief with follow-up actions
investigate_responder	member_email, analysis_id	Dig into one responder's trend and recommend shift changes

Code Mode (optional)

With --code-mode or ONCALLHEALTH_CODE_MODE=1 the catalog is exposed through FastMCP Code Mode: three meta-tools (search, get_schema, execute) let an agent discover tools on demand and chain calls in a sandboxed Python snippet. It saves context when an agent needs many calls per task, at the cost of hiding the tool list, annotations and output schemas from clients that read them directly. Off by default.

CLI reference

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

Hosted deployment (Streamable HTTP)

oncallhealth-mcp --transport http (or the Docker image, which runs uvicorn oncallhealth_mcp.transport:mcp_http_app) serves:

• POST /mcp: stateless Streamable HTTP MCP endpoint
• GET /health: unauthenticated health check

Every MCP request must carry the user's API key as Authorization: Bearer och_...; X-API-Key: och_... is accepted as well. Keys are verified against the On-Call Health API (successful checks are cached for five minutes) and unauthenticated requests get 401 before any tool runs. Tool calls are rate limited per key and per tool (for example analysis_run and analysis_start at 5/minute) identified from the JSON-RPC body, with 429 and Retry-After on excess.

Example remote client configuration (Claude Code):

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

Because the server is stateless you can run several uvicorn workers or replicas. For analysis_run background tasks to be shared across workers, point FastMCP's task backend at Redis or Valkey with FASTMCP_DOCKET_URL; the default in-memory backend is per process.

Set ONCALLHEALTH_MCP_ALLOWED_HOSTS=mcp.example.com to enable FastMCP's Host/Origin DNS-rebinding guard for the public host name.

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

Links

• On-Call Health - Main website
• API Documentation - REST API docs
• GitHub Issues - Report bugs

License

Apache-2.0