Rootly MCP Server

An MCP server for the Rootly API that integrates seamlessly with MCP-compatible editors like Cursor, Windsurf, and Claude. Resolve production incidents in under a minute without leaving your IDE.

Prerequisites

• Python 3.12 or higher
• uv package manager

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Rootly API token with appropriate permissions (see below)

API Token Permissions

The MCP server requires a Rootly API token. Choose the appropriate token type based on your needs:

• Global API Key (Recommended): Full access to all entities across your Rootly instance. Required for organization-wide visibility across teams, schedules, and incidents.
• Team API Key: Team Admin permissions with full read/edit access to entities owned by that team. Suitable for team-specific workflows.
• Personal API Key: Inherits the permissions of the user who created it. Works for individual use cases but may have limited visibility.

For full functionality of tools like get_oncall_handoff_summary, get_oncall_shift_metrics, and organization-wide incident search, a Global API Key is recommended.

Installation

Configure your MCP-compatible editor (tested with Cursor) with one of the configurations below. The package will be automatically downloaded and installed 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>"
      }
    }
  }
}

To customize allowed_paths and access additional Rootly API paths, clone the repository and use this configuration:

{
  "mcpServers": {
    "rootly": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/rootly-mcp-server",
        "rootly-mcp-server"
      ],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Connect to Hosted MCP Server

Alternatively, connect directly to our hosted MCP server:

{
  "mcpServers": {
    "rootly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.rootly.com/sse",
        "--header",
        "Authorization:${ROOTLY_AUTH_HEADER}"
      ],
      "env": {
        "ROOTLY_AUTH_HEADER": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}

Features

• Dynamic Tool Generation: Automatically creates MCP resources from Rootly's OpenAPI (Swagger) specification
• Smart Pagination: Defaults to 10 items per request for incident endpoints to prevent context window overflow
• API Filtering: Limits exposed API endpoints for security and performance
• Intelligent Incident Analysis: Smart tools that analyze historical incident data
  • find_related_incidents: Uses TF-IDF similarity analysis to find historically similar incidents
  • suggest_solutions: Mines past incident resolutions to recommend actionable solutions
• MCP Resources: Exposes incident and team data as structured resources for easy AI reference
• Intelligent Pattern Recognition: Automatically identifies services, error types, and resolution patterns

Available Tools

Alerts

• listIncidentAlerts
• listAlerts
• attachAlert
• createAlert

Environments

• listEnvironments
• createEnvironment

Functionalities

• listFunctionalities
• createFunctionality

Workflows

• listWorkflows
• createWorkflow

Incidents

• listIncidentActionItems
• createIncidentActionItem
• listIncident_Types
• createIncidentType
• search_incidents
• find_related_incidents
• suggest_solutions

On-Call

• get_oncall_shift_metrics
• get_oncall_handoff_summary
• get_shift_incidents

Services & Severities

• listServices
• createService
• listSeverities
• createSeverity

Teams & Users

• listTeams
• createTeam
• listUsers
• getCurrentUser

Meta

• list_endpoints

Why Path Limiting?

We limit exposed API paths for two key reasons:

1. Context Management: Rootly's comprehensive API can overwhelm AI agents, affecting their ability to perform simple tasks effectively
2. Security: Controls which information and actions are accessible through the MCP server

To expose additional paths, modify the allowed_paths variable in src/rootly_mcp_server/server.py.

Smart Analysis Tools

The MCP server includes intelligent tools that analyze historical incident data to provide actionable insights:

find_related_incidents

Finds historically similar incidents using text similarity analysis:

find_related_incidents(incident_id="12345", similarity_threshold=0.15, max_results=5)

• Input: Incident ID, similarity threshold (0.0-1.0), max results
• Output: Similar incidents with confidence scores, matched services, and resolution times
• Use Case: Get context from past incidents to understand patterns and solutions

suggest_solutions

Recommends solutions by analyzing how similar incidents were resolved:

suggest_solutions(incident_id="12345", max_solutions=3)
# OR for new incidents:
suggest_solutions(incident_title="Payment API errors", incident_description="Users getting 500 errors during checkout")

• Input: Either incident ID OR title/description text
• Output: Actionable solution recommendations with confidence scores and time estimates
• Use Case: Get intelligent suggestions based on successful past resolutions

How It Works

• Text Similarity: Uses TF-IDF vectorization and cosine similarity (scikit-learn)
• Service Detection: Automatically identifies affected services from incident text
• Pattern Recognition: Finds common error types, resolution patterns, and time estimates
• Fallback Mode: Works without ML libraries using keyword-based similarity
• Solution Mining: Extracts actionable steps from resolution summaries

Data Requirements

For optimal results, ensure your Rootly incidents have descriptive:

• Titles: Clear, specific incident descriptions
• Summaries: Detailed resolution steps when closing incidents
• Service Tags: Proper service identification

Example good resolution summary: "Restarted auth-service, cleared Redis cache, and increased connection pool from 10 to 50"

On-Call Shift Metrics

Get on-call shift metrics for any time period, grouped by user, team, or schedule. Includes primary/secondary role tracking, shift counts, hours, and days on-call.

get_oncall_shift_metrics(
    start_date="2025-10-01",
    end_date="2025-10-31",
    group_by="user"
)

On-Call Handoff Summary

Complete handoff: current/next on-call + incidents during shifts.

# All on-call (any timezone)
get_oncall_handoff_summary(
    team_ids="team-1,team-2",
    timezone="America/Los_Angeles"
)

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

Regional filtering shows only people on-call during business hours (9am-5pm) in the specified timezone.

Returns: schedules with current_oncall, next_oncall, and shift_incidents

Shift Incidents

Incidents during a time period, with filtering by severity/status/tags.

get_shift_incidents(
    start_time="2025-10-20T09:00:00Z",
    end_time="2025-10-20T17:00:00Z",
    severity="critical",  # optional
    status="resolved",    # optional
    tags="database,api"   # optional
)

Returns: incidents list + summary (counts, avg resolution time, grouping)

About Rootly AI Labs

This project was developed by Rootly AI Labs, where we're building the future of system reliability and operational excellence. As an open-source incubator, we share ideas, experiment, and rapidly prototype solutions that benefit the entire community.

Developer Setup & Troubleshooting

Prerequisites

• Python 3.12 or higher
• uv for dependency management

1. Set Up Virtual Environment

Create and activate a virtual environment:

uv venv .venv
source .venv/bin/activate  # Always activate before running scripts

2. Install Dependencies

Install all project dependencies:

uv pip install .

To add new dependencies during development:

uv pip install <package>

3. Set Up Git Hooks (Recommended for Contributors)

Install pre-commit hooks to automatically run linting and tests before commits:

./scripts/setup-hooks.sh

This ensures code quality by running:

• Ruff linting
• Pyright type checking
• Unit tests

4. Verify Installation

The server should now be ready to use with your MCP-compatible editor.

For developers: Additional testing tools are available in the tests/ directory.