oncallhealth-mcp
[PyPI version]
[Python 3.10+]
MCP server for On-Call Health burnout analysis. Connects AI assistants to your on-call data for workload insights.
Prerequisites
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 Desktop
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):
Cursor
Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
VS Code / GitHub Copilot
Add to .vscode/mcp.json in your project:
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
Codex CLI
Gemini CLI
Manual / other clients
Or run without installing: ONCALLHEALTH_API_KEY=och_live_... uvx oncallhealth-mcp.
Configuration
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.
OCH scores run 0-100; higher means more at risk. Scores inform staffing decisions and are not a medical diagnosis.
Resources
Prompts
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
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):
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.
Links
License
Apache-2.0