Skip to main content

​
Introduction

The Rootly MCP Server implements the Model Context Protocol to expose Rootly incident data and actions as tools that any MCP-compatible client can use. This means you can query incidents, check on-call schedules, find similar past incidents, and take action — all from within Cursor, Windsurf, Claude Code, Gemini CLI, or any other MCP-compatible environment. The server dynamically generates tools from Rootly’s OpenAPI specification, so it always reflects the current API surface. It also includes a set of intelligent tools built on top of that foundation:
  • find_related_incidents — uses TF-IDF similarity analysis to surface historically similar incidents
  • suggest_solutions — mines past incident resolutions to recommend actionable next steps
  • get_oncall_shift_metrics — shift counts, hours, and days on-call grouped by user, team, or schedule
  • get_oncall_handoff_summary — current and next on-call plus incidents during shifts, with optional regional filtering
  • get_shift_incidents — incidents during a time window, filterable by severity, status, and tags

​
Before You Begin

Before connecting the Rootly MCP Server, make sure you have a Rootly API token. Generate one in Account > Manage API keys > Generate New API Key. Choose the token type based on your needs:
Token TypeAccess Level
Global API Key (recommended)Full access across all teams, schedules, and incidents
Team API KeyFull read/write access scoped to a single team
Personal API KeyInherits the permissions of the user who created it
Tools like get_oncall_handoff_summary and get_oncall_shift_metrics require organization-wide visibility. A Global API Key is recommended for full functionality.
For local installation, you also need:
  • Python 3.12 or higher
  • The uv package manager

​
Installation

Choose the deployment option that fits your team. The hosted option is the fastest way to get started and requires no local setup. Connect to Rootly’s managed MCP server — always up to date, zero maintenance. Streamable HTTP (preferred): 
{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
SSE (backward compatible): 
{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

​
Claude Code

claude mcp add rootly --transport streamable-http https://mcp.rootly.com/mcp \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
SSE fallback: 
claude mcp add rootly-sse --transport sse https://mcp.rootly.com/sse \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"

​
Gemini CLI

Install as an extension: 
gemini extensions install https://github.com/Rootly-AI-Labs/Rootly-MCP-server
Or configure manually in ~/.gemini/settings.json: 
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

​
Local Installation

The package is downloaded automatically when you first open your editor. With uv: 
{
  "mcpServers": {
    "rootly": {
      "command": "uv",
      "args": ["tool", "run", "--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
With uvx: 
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

​
Self-Hosted

For organizations that need full control over infrastructure or data flow: 
git clone https://github.com/Rootly-AI-Labs/Rootly-MCP-server
cd Rootly-MCP-server
uv pip install .
Run with Docker (Streamable HTTP): 
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=streamable-http \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
Run with Docker (SSE): 
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=sse \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
The MCP server is now connected. Your MCP client can call Rootly tools to list incidents, check on-call schedules, find related incidents, and more.

​
Example Tools

​
On-Call Shift Metrics

Get shift counts, hours, and days on-call for any time period, grouped by user, team, or schedule: 
get_oncall_shift_metrics(
    start_date="2025-10-01",
    end_date="2025-10-31",
    group_by="user"
)

​
On-Call Handoff Summary

Get current and next on-call responders plus incidents that occurred during their shifts. Supports optional regional filtering to show only responders on-call during business hours in a given timezone: 
get_oncall_handoff_summary(
    team_ids="team-1,team-2",
    timezone="America/Los_Angeles"
)

# Show only APAC on-call during APAC business hours
get_oncall_handoff_summary(
    timezone="Asia/Tokyo",
    filter_by_region=True
)

​
Shift Incidents

Incidents during a time window, filterable by severity, status, and tags. Returns an incident list plus a summary with counts and average resolution time: 
get_shift_incidents(
    start_time="2025-10-20T09:00:00Z",
    end_time="2025-10-20T17:00:00Z",
    severity="critical",
    status="resolved",
    tags="database,api"
)

​
On-Call Health Integration

The MCP server integrates with On-Call Health to detect workload health risk in scheduled responders. Set the ONCALLHEALTH_API_KEY environment variable to enable it: 
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "your_rootly_token",
        "ONCALLHEALTH_API_KEY": "och_live_your_key"
      }
    }
  }
}
Then call: 
check_oncall_health_risk(
    start_date="2026-02-09",
    end_date="2026-02-15"
)
Returns at-risk users who are scheduled on-call, recommended safe replacements, and action summaries.

​
Troubleshooting

Some MCP clients require a restart after adding a new server configuration. Fully restart your editor or AI assistant after saving the configuration. Also confirm that the JSON configuration is valid — a missing comma or bracket will silently prevent the server from loading.
Confirm that the API token is active and has not been revoked. Go to Account > Manage API keys in Rootly and verify the key exists. Also check that the token is passed correctly — for hosted configurations it goes in the Authorization header as Bearer <token>, and for local/self-hosted it goes in the ROOTLY_API_TOKEN environment variable.
Tools like get_oncall_handoff_summary and get_oncall_shift_metrics require visibility across all teams. If results are incomplete, your API token may be scoped to a single team. Switch to a Global API Key for full access.
Confirm that Python 3.12 or higher is installed (python --version) and that uv is available (uv --version). If using uvx, the package is downloaded on first run — ensure you have network access. For proxy environments, you may need to configure uv proxy settings.
The check_oncall_health_risk tool only appears when ONCALLHEALTH_API_KEY is set. Confirm the environment variable is present in your MCP server configuration and that the key is valid at oncallhealth.ai.

API Reference

Browse the full Rootly API — all endpoints exposed by the MCP server come from here.

Rootly AI

Learn about Rootly’s built-in AI features for incident management.

MCP Server on GitHub

Source code, issues, and release notes for the Rootly MCP Server.