MCP Server - Rootly

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 Type	Access Level
Global API Key (recommended)	Full access across all teams, schedules, and incidents
Team API Key	Full read/write access scoped to a single team
Personal API Key	Inherits 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.

Hosted (recommended)

Connect to Rootly’s managed MCP server — always up to date, zero maintenance. Transport Options:

Streamable HTTP: https://mcp.rootly.com/mcp
SSE: https://mcp.rootly.com/sse
Code Mode: https://mcp.rootly.com/mcp-codemode

Default Configuration (Streamable HTTP):

{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

SSE Alternative:

{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Code Mode:

{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp-codemode",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Client-Specific Setup

Claude Code

Streamable HTTP:

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

Code Mode:

claude mcp add rootly-codemode --transport http https://mcp.rootly.com/mcp-codemode \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"

SSE Alternative:

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

Manual Configuration - Create .mcp.json in your project root:

{
  "mcpServers": {
    "rootly": {
      "type": "http",
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ROOTLY_API_TOKEN"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rootly": {
      "serverUrl": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "rootly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.rootly.com/mcp",
        "--transport",
        "http",
        "--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. Local installation provides additional security controls not available in the hosted version. 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>"
      }
    }
  }
}

Security Controls (Local Only)

Local installations support granular permission controls through environment variables: Default Mode (All Tools):

{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
    // All tools available by default, matching hosted behavior
  }
}

Read-Only Mode (Restricted):

{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
    "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "false"
  }
}

Restrict to Specific Tools:

{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
    "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "true",
    "ROOTLY_MCP_ENABLED_TOOLS": "createIncident,getIncident,listTeams,getCurrentUser"
  }
}

Full Access by Default — Local installations match hosted behavior with all tools available. Use ROOTLY_MCP_ENABLE_WRITE_TOOLS=false to restrict to read-only mode.

Environment Variables:

Variable	Description	Default
`ROOTLY_API_TOKEN`	Your Rootly API authentication token	Required
`ROOTLY_MCP_ENABLE_WRITE_TOOLS`	Enable write operations (create, update)	`true`
`ROOTLY_MCP_ENABLED_TOOLS`	Comma-separated allowlist of specific tools	All available tools

Example: Minimal Write Access for Automation:

{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
    "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "true",
    "ROOTLY_MCP_ENABLED_TOOLS": "createIncidentActionItem,updateIncidentFormFieldSelection,listIncidents,getIncident"
  }
}

This configuration allows only creating action items and updating form fields — perfect for automation that needs to add findings without modifying incident status or severity. Discovering Available Tools: To see all available tool names for your configuration:

ROOTLY_API_TOKEN=<YOUR_TOKEN> \
uvx --from rootly-mcp-server rootly-mcp-server --list-tools

With write tools enabled:

ROOTLY_API_TOKEN=<YOUR_TOKEN> \
ROOTLY_MCP_ENABLE_WRITE_TOOLS=true \
uvx --from rootly-mcp-server rootly-mcp-server --list-tools

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

Run with Docker (Dual Transport + Code Mode):

docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=both \
  -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.

Alternative: Rootly CLI — For terminal-based workflows, check out the Rootly CLI which provides direct command-line access to incidents, alerts, and on-call operations.

Available Tools

The MCP server exposes 100+ tools dynamically generated from Rootly’s OpenAPI specification, plus custom agentic tools for intelligent incident analysis.

Custom Agentic Tools

check_oncall_health_risk — detects workload health risk in scheduled responders
check_responder_availability — checks responder availability
collect_incidents — collects incident data with filtering
createIncident — create incidents with scoped fields for agent workflows
create_override_recommendation — suggests on-call override recommendations
find_related_incidents — uses TF-IDF similarity to find historically similar incidents
getIncident — retrieve single incidents with PIR-related fields
get_alert_by_short_id — get alerts using short IDs
get_oncall_handoff_summary — complete handoff information
get_oncall_schedule_summary — schedule overview
get_oncall_shift_metrics — comprehensive shift analytics
get_server_version — server version information
get_shift_incidents — incidents during specific time periods
list_endpoints — available API endpoints
list_incidents — incident listing with filters
list_shifts — on-call shift information
search_incidents — advanced incident search
suggest_solutions — mines past resolutions for actionable recommendations
updateIncident — scoped incident updates for summary and retrospective progress

OpenAPI-Generated Tools

The server includes all standard Rootly API operations for comprehensive incident management, including tools for alerts, environments, escalation policies, functionalities, incident types, on-call roles, schedules, services, severities, teams, workflows, and more.

Example Skills

Rootly Incident Responder

The MCP server includes a pre-built Rootly Incident Responder skill for Claude Code that demonstrates a complete incident response workflow:

Analyzes production incidents with full context
Finds similar historical incidents using ML-based similarity matching
Suggests solutions based on past successful resolutions
Coordinates with on-call teams across timezones
Correlates incidents with recent code changes and deployments
Creates action items and remediation plans
Provides confidence scores and time estimates

Quick Start:

# Copy the skill to your project
mkdir -p .claude/skills
curl -o .claude/skills/rootly-incident-responder.md \
  https://raw.githubusercontent.com/Rootly-AI-Labs/rootly-mcp-server/main/examples/skills/rootly-incident-responder.md

# Then in Claude Code, invoke it:
# @rootly-incident-responder analyze incident #12345

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

The server connects but tools are not appearing

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.

Authentication errors when calling tools

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.

Organization-wide tools return incomplete data

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.

The local server fails to start

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.

On-Call Health tools are not available

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.

Overview & General

CLI & Developer Tools

Communication & Collaboration

Alerting & Monitoring

Observability & APM

Documentation & Knowledge Management

Issue & Project Management

Video Conferencing

Development & CI/CD

Status & Communication

Data & Analytics

AI & Automation

Infrastructure & Security

Calendar & Scheduling

Service Catalogs

​Introduction

​Before You Begin

​Installation

​Hosted (recommended)

​Client-Specific Setup

​Claude Code

​Cursor

​Windsurf

​Claude Desktop

​Gemini CLI

​Local Installation

​Security Controls (Local Only)

​Self-Hosted

​Available Tools

​Custom Agentic Tools

​OpenAPI-Generated Tools

​Example Skills

​Rootly Incident Responder

​Example Tools

​On-Call Shift Metrics

​On-Call Handoff Summary

​Shift Incidents

​On-Call Health Integration

​Troubleshooting

​Related Pages

API Reference

Rootly AI

MCP Server on GitHub

Introduction

Before You Begin

Installation

Hosted (recommended)

Client-Specific Setup

Claude Code

Cursor

Windsurf

Claude Desktop

Gemini CLI

Local Installation

Security Controls (Local Only)

Self-Hosted

Available Tools

Custom Agentic Tools

OpenAPI-Generated Tools

Example Skills

Rootly Incident Responder

Example Tools

On-Call Shift Metrics

On-Call Handoff Summary

Shift Incidents

On-Call Health Integration

Troubleshooting

Related Pages