> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use the Rootly MCP Server to manage incidents directly from your IDE or AI assistant, with no context switching and hosted or self-hosted deployment options.

## Introduction

The Rootly MCP Server implements the [Model Context Protocol](https://modelcontextprotocol.io) 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    |

<Callout icon="triangle-exclamation" color="#FEF3C7">
  Tools like `get_oncall_handoff_summary` and `get_oncall_shift_metrics` require organization-wide visibility. A Global API Key is recommended for full functionality.
</Callout>

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):**

```json theme={null}
{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

**SSE Alternative:**

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

**Code Mode:**

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

### Client-Specific Setup

#### Claude Code

**Streamable HTTP:**

```bash theme={null}
claude mcp add --transport http rootly https://mcp.rootly.com/mcp \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
```

**Code Mode:**

```bash theme={null}
claude mcp add rootly-codemode --transport http https://mcp.rootly.com/mcp-codemode \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
```

**SSE Alternative:**

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

#### Windsurf

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

```json theme={null}
{
  "mcpServers": {
    "rootly": {
      "serverUrl": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

#### Codex

Add to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.rootly]
url = "https://mcp.rootly.com/mcp"
bearer_token_env_var = "ROOTLY_API_TOKEN"
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

<Callout icon="info-circle" color="#E0F2FE">
  The `--transport http` flag ensures HTTP streamable transport is used instead of auto-falling back to SSE.
</Callout>

```json theme={null}
{
  "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:

```bash theme={null}
gemini extensions install https://github.com/Rootly-AI-Labs/Rootly-MCP-server
```

Or configure manually in `~/.gemini/settings.json`:

```json theme={null}
{
  "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`:**

```json theme={null}
{
  "mcpServers": {
    "rootly": {
      "command": "uv",
      "args": ["tool", "run", "--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
        "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "true"
      }
    }
  }
}
```

**With `uvx`:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
    // All tools available by default, matching hosted behavior
  }
}
```

**Read-Only Mode (Restricted):**

```json theme={null}
{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
    "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "false"
  }
}
```

**Restrict to Specific Tools:**

```json theme={null}
{
  "env": {
    "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
    "ROOTLY_MCP_ENABLE_WRITE_TOOLS": "true",
    "ROOTLY_MCP_ENABLED_TOOLS": "createIncident,getIncident,listTeams,getCurrentUser"
  }
}
```

<Callout icon="info-circle" color="#E0F2FE">
  **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.
</Callout>

**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:**

```json theme={null}
{
  "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:

```bash theme={null}
ROOTLY_API_TOKEN=<YOUR_TOKEN> \
uvx --from rootly-mcp-server rootly-mcp-server --list-tools
```

With write tools enabled:

```bash theme={null}
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:

```bash theme={null}
git clone https://github.com/Rootly-AI-Labs/Rootly-MCP-server
cd Rootly-MCP-server
uv pip install .
```

Both hosted and self-hosted deployments expose the same curated tool surface by default, including write-enabled tools. To restrict to read-only tools, start the server with `--no-enable-write-tools` or set `ROOTLY_MCP_ENABLE_WRITE_TOOLS=false`.

To expose only a specific subset of MCP tools, set `ROOTLY_MCP_ENABLED_TOOLS` (or pass `--enabled-tools`) with a comma-separated allowlist of exact tool names.

**Discover available tool names:**

```bash theme={null}
ROOTLY_API_TOKEN=<YOUR_TOKEN> \
uv run python -m rootly_mcp_server --list-tools
```

**Smoke-test a self-hosted allowlist:**

```bash theme={null}
ROOTLY_API_TOKEN=<YOUR_TOKEN> \
ROOTLY_MCP_ENABLED_TOOLS=list_incidents,getIncident,get_server_version \
uv run python -m rootly_mcp_server --transport streamable-http --log-level ERROR
```

Then connect an MCP client to `http://127.0.0.1:8000/mcp` and verify `tools/list` returns only the specified tools.

**Run with Docker (Streamable HTTP):**

```bash theme={null}
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=streamable-http \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  -e ROOTLY_MCP_ENABLE_WRITE_TOOLS=true \
  rootly-mcp-server
```

**Run with Docker (SSE):**

```bash theme={null}
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):**

```bash theme={null}
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=both \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
```

<Callout icon="circle-check" color="#DCFCE7">
  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.
</Callout>

<Callout icon="info-circle" color="#E0F2FE">
  **Alternative: Rootly CLI** — For terminal-based workflows, check out the [Rootly CLI](/integrations/cli) which provides direct command-line access to incidents, alerts, and on-call operations.
</Callout>

## Available Tools

The MCP server exposes **150+ 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 also includes all standard Rootly API operations — covering alerts, escalation policies, schedules, services, teams, workflows, dashboards, playbooks, post-incident reviews, and more. Security-sensitive operations (API key management, user creation/deletion, role management, webhook configuration) and delete operations are excluded from the default tool surface.

To see the exact tools available under your configuration:

```bash theme={null}
ROOTLY_API_TOKEN=<YOUR_TOKEN> \
uvx --from rootly-mcp-server rootly-mcp-server --list-tools
```

For the complete tool inventory and pre-built workflow subsets (Incident Response, On-Call Management, Monitoring & Alerting, Post-Incident Analysis, Analytics & Reporting), see the [README on GitHub](https://github.com/Rootly-AI-Labs/Rootly-MCP-server#supported-tools).

## Workflow-Focused Tool Subsets

With 150+ tools available, you can configure focused subsets for optimal AI agent performance using `ROOTLY_MCP_ENABLED_TOOLS`. Pre-built subsets are available for:

| Subset                     | Tools | Use Case                                          |
| -------------------------- | ----- | ------------------------------------------------- |
| **Incident Response**      | 25    | Emergency responders and incident commanders      |
| **On-Call Management**     | 35    | Schedule coordinators and on-call managers        |
| **Monitoring & Alerting**  | 41    | Platform teams setting up observability           |
| **Post-Incident Analysis** | 30    | SREs doing retrospectives and process improvement |
| **Analytics & Reporting**  | 15    | Leadership and metrics teams (read-only)          |

Copy-paste ready tool lists for each subset are maintained in the [GitHub README](https://github.com/Rootly-AI-Labs/Rootly-MCP-server#workflow-focused-tool-subsets).

You can also run multiple MCP instances with different tool subsets for different teams:

```json theme={null}
{
  "mcpServers": {
    "rootly-incident-response": {
      "command": "uvx",
      "args": ["--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>",
        "ROOTLY_MCP_ENABLED_TOOLS": "<paste subset from GitHub README>"
      }
    }
  }
}
```

## MCP Resources

AI agents can access these resources for situational awareness:

| Resource                   | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `incident://{incident_id}` | Detailed incident information for specific incidents |
| `team://{team_id}`         | Team details including name, color, and metadata     |
| `rootly://incidents`       | List of recent incidents for quick reference         |
| `rootly://oncall-status`   | Current on-call status across all schedules          |
| `rootly://workflow-guide`  | Step-by-step workflow guidance for common operations |

Example usage: *"Check the current on-call status"* → AI reads `rootly://oncall-status` resource.

## Example Skills

### Rootly Incident Responder

The MCP server includes a pre-built [Rootly Incident Responder skill](https://github.com/Rootly-AI-Labs/rootly-mcp-server/blob/main/examples/skills/rootly-incident-responder.md) 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:**

```bash theme={null}
# 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:

```python theme={null}
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:

```python theme={null}
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](https://oncallhealth.ai) to detect workload health risk in scheduled responders. Set the `ONCALLHEALTH_API_KEY` environment variable to enable it:

```json theme={null}
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["--from", "rootly-mcp-server", "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

<AccordionGroup>
  <Accordion title="The server connects but tools are not appearing" icon="wrench">
    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.
  </Accordion>

  <Accordion title="Authentication errors when calling tools" icon="lock">
    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.
  </Accordion>

  <Accordion title="Organization-wide tools return incomplete data" icon="magnifying-glass">
    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.
  </Accordion>

  <Accordion title="The local server fails to start" icon="terminal">
    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.
  </Accordion>

  <Accordion title="On-Call Health tools are not available" icon="heart-pulse">
    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.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Browse the full Rootly API — all endpoints exposed by the MCP server come from here.
  </Card>

  <Card title="Rootly AI" icon="robot" href="/ai/ai">
    Learn about Rootly's built-in AI features for incident management.
  </Card>

  <Card title="MCP Server on GitHub" icon="github" href="https://github.com/Rootly-AI-Labs/Rootly-MCP-server">
    Source code, issues, and release notes for the Rootly MCP Server.
  </Card>
</CardGroup>