Rootly API Patterns

Rootly MCP Tools & API Patterns

Overview

Rootly exposes a hosted MCP server at mcp.rootly.com built with FastMCP. When accessed through the MCP Gateway, credentials are injected automatically via the Authorization: Bearer header — no manual token handling is required. The MCP server generates its 25 tools dynamically from Rootly's OpenAPI specification and exposes a curated subset of the full REST API.

The Rootly REST API follows the JSON:API specification (application/vnd.api+json), using page-number-based pagination and relationship includes.

Authentication

Token Types

For the MCP Gateway, use a Global Token to ensure all incident management tools work without permission errors.

Generate: Rootly web UI → Account → Manage API Keys → Generate New API Key

How the Gateway Injects Credentials

When using Rootly through the MCP Gateway, the API token is stored as an org credential and automatically forwarded as:

Authorization: Bearer <org-api-token>

No additional configuration is needed in the MCP tool calls.

Complete MCP Tool Reference

Intelligent Incident Analysis

On-Call Management

Core Incident Management

Alerts

Configuration & Metadata

Teams & Users

JSON:API Pagination

Rootly's REST API uses page-number-based pagination following the JSON:API spec:

Request Parameters

Pagination Pattern

1. Call the list tool with page[number]=1, page[size]=50
2. Check the response meta.total_count to determine total records
3. Increment page[number] until you have all records:
   • total_pages = ceil(total_count / page_size)
4. Continue fetching until page[number] > total_pages

Example: Fetch all open incidents:

• Call incidents_get with page[number]=1, page[size]=50
• Check meta.total_count; if 120 total, you need 3 pages (50 + 50 + 20)
• Repeat with page[number]=2 and page[number]=3

Response Structure (JSON:API)

{
  "data": [
    {
      "id": "abc-123",
      "type": "incidents",
      "attributes": {
        "title": "API gateway latency spike",
        "status": "in_triage",
        "sequential_id": 342
      },
      "relationships": {
        "severity": { "data": { "id": "sev-id", "type": "severities" } },
        "services": { "data": [{ "id": "svc-id", "type": "services" }] }
      }
    }
  ],
  "meta": {
    "total_count": 120,
    "total_pages": 3,
    "current_page": 1
  }
}

Common Query Patterns

Filter Active Incidents by Status

Call incidents_get with status=in_triage or status=detected to find open incidents.

Filter by Severity

Call incidents_get with severity=critical (use the slug from severities_get) to focus on the highest-priority incidents.

Lookup IDs Before Creating Resources

Rootly uses UUIDs for all resource IDs. Before creating an incident, always:

1. Call severities_get → use the matching severity's id
2. Call services_get → use the affected service's id
3. Call teams_get → use the responding team's id

Discover Endpoints Dynamically

Call list_endpoints to get the current full list of available API endpoints. This is useful when the MCP server has been updated to expose new Rootly API endpoints.

Rate Limiting

Rootly applies rate limits at the API level. The MCP server does not expose rate limit headers, but:

• Avoid fetching all records in rapid succession for large datasets
• Use page[size] to limit response sizes (max 100 per page)
• If you receive a 429, wait 30-60 seconds before retrying
• Prefer filtering server-side to reduce total API calls

Error Handling

Common Errors

Best Practices

1. Use list_endpoints to discover tools — The MCP server generates tools dynamically; new endpoints appear automatically after Rootly API updates
2. Look up IDs, don't guess — Always call severities_get, services_get, and teams_get before creating incidents
3. Paginate large datasets — Set page[size]=50 and iterate pages rather than fetching all at once
4. Use AI tools first — find_related_incidents and suggest_solutions often resolve incidents faster than manual investigation
5. Filter server-side — Use status and severity parameters in incidents_get rather than fetching all and filtering locally
6. Use Global tokens in the gateway — Team tokens will cause 403 errors for cross-team incident queries

Related Skills

• Incidents — Incident lifecycle, AI analysis, action items
• On-Call Management — Handoff summaries, shift metrics, health risk