How to connect Rootly MCP with Codex

List all available Rootly API endpoints with their descriptions.

Get the Rootly MCP server version. Returns the current version of the deployed MCP server. Useful for checking if the server has been updated.

🚨 List incidents with structured filters - ESSENTIAL for incident response. WHEN TO USE: • During incident response to check for related ongoing incidents • For shift handoffs to review recent incidents by team/service • For post-incident analysis to find patterns by severity/date range • For audit workflows requiring specific filtering criteria Use this when you need date-range, team, service, severity, or status filters. For simple text searches, prefer search_incidents instead. Argument caps: page_size <= 100. Values outside the bounds are clamped and reported, not rejected.

Collect a bounded working set of incidents across multiple pages for audits and analysis. Use this instead of list_incidents when you want a compact batch of incidents in one tool call, while keeping payload size under control. Argument caps: max_results <= 100, batch_size between 10 and 100. Values outside those bounds are clamped and reported, not rejected.

Search incidents with flexible pagination control. Use page_number=0 to fetch all matching results across multiple pages. Use page_number>0 to fetch a specific page. max_results (also accepted as `limit`) caps how many incidents come back in either mode: across pages when page_number=0, and within the page otherwise. Left unset, a single page returns page_size incidents and page_number=0 stops at 5. Argument caps: page_size <= 20, max_results <= 10. Values outside those bounds are clamped and reported, not rejected.

Retrieve a single incident with PIR-related fields for direct verification.

Fetch the written retrospective for one incident. Answers "what did we learn from INC-4460" in a single call. Returns the document's title, content and status alongside the incident it belongs to, and reports the incident's retrospective progress so a blank document is distinguishable from one nobody has started. The route exists only in this direction: `/post_mortems` cannot be filtered by incident, and the document carries no reference back to one, so the id has to come from the incident's own relationship. Doing that here keeps a caller from having to know it. Use `list_incident_post_mortems` to search across retrospectives instead.

Browse retrospectives across incidents. Answers "the last five retrospectives", "published ones for this team since June", or "how many are still draft". Each result carries the document's analysis -- summary, causes, impact, actions. A recognised Timeline is dropped and the record says so with `timeline_omitted`, because a minute-by-minute log is a third of a document and rarely what a browse is after. What remains is still capped, and a record cut that way carries `content_truncated` with its real `content_chars`. Use `get_incident_retrospective` for one document whole, Timeline included and nothing cut. Filtering happens upstream for status, severity, team, service and dates. Free-text search is not offered here because the API's search matches titles only, and titles are generated from the incident name -- it cannot find a retrospective by what it says. Use `get_incident_retrospective` when the incident is already known.

List role assignments for an incident (who is Commander, Scribe, etc.). Returns one entry per defined role with role metadata and the assigned user (or `user_id: null` for roles that are defined on the incident but not yet assigned). Use this to answer questions like "who is the incident commander?", "is there a postmortem owner?", or "list all roles for INC-4460". Implementation note: this wraps `GET /v1/incidents/{id}?include=roles` and flattens the JSON:API `included` array of `incident_role_assignments` into a flat table so callers don't need to walk the relationships graph.

Read what was said on an incident's calls (Rootly Meeting Scribe). Returns the spoken transcript of each recorded call for the incident, as text per speaker turn, alongside Scribe's own summary. Covers Google Meet, Zoom and Microsoft Teams calls that Scribe recorded. Use this to catch up on a call you missed, or to pull decisions and actions out of an incident bridge. Recordings where nobody spoke are skipped rather than returned empty.

Create an incident with a scoped set of fields for agent-driven workflows.

Update native incident fields via ``PUT /v1/incidents/{id}``. Only the arguments you provide are sent, so unspecified fields — including the lifecycle ``status`` — are left untouched.

🔍 Find historically similar incidents using ML similarity analysis - CRITICAL for incident response. WHEN TO USE: • EARLY in incident response to learn from past similar issues • When you're unsure about root cause or resolution approach • Before escalating to find if this is a known pattern • For post-incident analysis to identify recurring issues Provide either incident_id OR incident_description (e.g., 'website is down', 'database timeout errors'). Use status_filter to limit to specific incident statuses or leave empty for all incidents. Argument caps: max_results <= 20. Values outside the bounds are clamped and reported, not rejected.

💡 Get actionable solution recommendations from similar resolved incidents - KEY for incident response. WHEN TO USE: • AFTER find_related_incidents to get specific resolution steps • When team is stuck on how to resolve the current incident • To speed up incident resolution with proven solutions • For training new responders on resolution patterns Provide either incident_id OR title/description. Defaults to resolved incidents for solution mining. Argument caps: max_solutions <= 10. Values outside the bounds are clamped and reported, not rejected.

📊 Get on-call workload metrics and shift statistics - ESSENTIAL for fairness and planning. WHEN TO USE: • Monthly/quarterly reviews of on-call distribution • Before adjusting schedules to ensure fair workload • For management reporting on on-call burden • When investigating potential on-call burnout Returns shift counts, total hours, and statistics grouped by user, schedule, or team. Examples: - Monthly report: start_date='2025-10-01', end_date='2025-10-31' - Specific user: start_date='2025-10-01', end_date='2025-10-31', user_ids='123,456' - Specific team: team_ids='team-1' (will query schedules for that team first)

Get current on-call handoff summary. Shows who's currently on-call and who's next. Optionally fetch incidents (set include_incidents=True, but slower). Each responder's `role` is their On-Call role (e.g. Responder, Admin); shifts themselves carry no role. Use filter_by_region=True with a timezone to see only people on-call during business hours in that region (e.g., timezone='Asia/Tokyo', filter_by_region=True shows only APAC on-call during APAC business hours). Useful for: - Quick on-call status checks - Daily handoff meetings - Regional on-call status (APAC, EU, Americas) - Team coordination across timezones

Get incidents and alerts that occurred during a specific shift or time period. Useful for: - Shift handoff summaries showing what happened during the shift - Post-shift debriefs and reporting - Incident analysis by time period - Understanding team workload during specific shifts Returns incident details including severity, status, duration, and basic summary.

List shifts for one schedule over a date range. Replaces the generated getScheduleShifts, which passed the range straight through and failed with `Datetime range exceeds 1 month` on anything longer than the upstream accepts. Ranges longer than that are split into windows and merged here, so a two-month question is a normal request. Use list_shifts instead when the question spans schedules or filters by user.

List on-call shifts with reliable filtering, enrichment, and MCP-level pagination. Unlike the raw API, this tool: - Actually filters by user_ids (client-side filtering) - Includes user_name, user_email, schedule_name, team_name - Calculates total_hours for each shift - Returns a predictable paginated result for MCP clients Use this instead of the auto-generated listShifts when you need user filtering or dependable pagination on large tenants. Answers questions about *individual* shifts: who is on call at a given time, when a handoff happens, which shifts were overrides, or one person's schedule (via user_ids). For questions about totals across a team -- hours per responder, coverage, load -- use get_oncall_schedule_summary, whose response size depends on team size rather than on how long a range you asked for. Ranges longer than the upstream cap are split into windows and merged automatically, so a multi-month range is a normal request.

Get compact on-call schedule summary for a date range. Returns one entry per user per schedule (not raw shifts), with aggregated hours. Optimized for AI agent context windows. Use this instead of list_shifts when you need: - Aggregated hours per responder - Schedule coverage overview - Responder load analysis with warnings One row per user per schedule, so the response stays the same size whether the range is a week or a year. For individual shift times, or for one person's schedule, use list_shifts instead. Ranges longer than the upstream cap are split into windows and merged automatically.

Check if specific users are scheduled for on-call in a date range. Use this to verify if at-risk users (from On-Call Health) are scheduled, or to check availability before assigning new shifts. Returns scheduled users with their shifts and total hours, plus users who are not scheduled. Shift times and hours are clipped to the requested window; date-only end dates include that entire UTC day.

Recommend replacement responders for an override shift. Finds users in the same schedule rotation who are not already heavily loaded during the period. Returns recommended replacements sorted by current load (lowest first), plus a ready-to-use override payload for the top recommendation.

Get alert details by short_id or alert URL. Use this when a user pastes an alert URL or short_id from a pager notification and wants to investigate the alert.

Read the Rootly audit log: who changed which configuration object, when, and what changed. Each record carries the action, the acting user, the source, and the before-and-after value of every modified field. Use it to answer "who changed this escalation policy", "what did this workflow look like before", or to collect change evidence for a compliance review. Covers roughly 60 resource types at the object level and is retained indefinitely. Two limits worth knowing: schedule rotations, escalation levels and shift overrides are not audited, and sign-in events are kept separately from this log. Returns a single page of at most 25 records, newest first, alongside `total_matching` so a wider search can be narrowed with the filters. It does not walk the whole log, so a full compliance export belongs on the REST endpoint rather than here. Requires an API token whose role has the "Audits - read" permission.

List AI SRE investigations you can see, newest first.

Get an investigation's verdict: summary, root cause, confidence, hypotheses, evidence, causal chain and open_questions (what Rootly couldn't verify, so you can check them with tools only you have).

Follow a running investigation. Returns new steps and tool calls since after_cursor, waiting up to wait_seconds for them. Keep calling with after_cursor=next_cursor until done is true.

Start an AI SRE investigation on one alert or incident. Then follow it with get_investigation_progress.

Cancel a running investigation.

List alert_events

Creates a new alert event

Retrieves a specific alert_event by id

Updates a specific alert event. Only alert events with kind 'note' (user-created notes) can be updated. System-generated events are immutable to maintain audit trail integrity.

List alert groups

Creates a new alert group. **Note**: For enhanced functionality and future compatibility, consider using the advanced alert grouping with `conditions` field instead of the legacy `group_by_alert_title`, `group_by_alert_urgency`, and `attributes` fields.

Retrieves a specific alert group by id

Update a specific alert group by id. **Note**: For enhanced functionality and future compatibility, consider using the advanced alert grouping with `conditions` field instead of the legacy `group_by_alert_title`, `group_by_alert_urgency`, and `attributes` fields.

List all alert routes for the current team with filtering and pagination. **Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.**

Creates a new alert route from provided data. **Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.** ## Asynchronous Rule Creation For organizations with large numbers of routing rules, Rootly supports asynchronous rule processing to improve performance. When enabled, rule creation happens in the background. Asynchronous processing is also applied automatically, whether or not it is enabled for your organization, when a request carries a rule graph too large to save within the request timeout. Size is measured in total dependent records — rules plus their condition groups, conditions and destinations — and for an update it includes the rules already on the route, not just those in the payload. **Important**: Whenever rules are processed asynchronously, the rules list in the API response will not be up-to-date immediately after creation. You should refetch the alert route, or poll the async rule creation status endpoint with the `request_id` you supplied, to confirm the rules have landed. If you experience slow operations when managing alert routes with many rules, contact Rootly customer support to enable asynchronous rule processing for your organization.

Get a specific alert route by id. **Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.** ## Optional Parameters - **show_nested_ids** (query parameter): When set to `true`, the response will include IDs for all nested resources (destinations, condition_groups, conditions). This is useful when you need to reference these nested resources for updates or deletions via PATCH requests. Example: `GET /v1/alert_routes/{id}?show_nested_ids=true`

Update a specific alert route by id. **Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.** ### Asynchronous Rule Creation For organizations with large numbers of routing rules, Rootly supports asynchronous rule processing to improve performance. When enabled, rule updates happen in the background. Asynchronous processing is also applied automatically, whether or not it is enabled for your organization, when a request carries a rule graph too large to save within the request timeout. Size is measured in total dependent records — rules plus their condition groups, conditions and destinations — and includes the rules already on the route, not just those in the payload, so a small payload against a large route may still be processed asynchronously. **Important**: Whenever rules are processed asynchronously, the rules list in the API response will not be up-to-date immediately after update. You should refetch the alert route, or poll the async rule creation status endpoint with the `request_id` you supplied, to confirm the rules have landed. If you experience slow operations when managing alert routes with many rules, contact Rootly customer support to enable asynchronous rule processing for your organization.

Updates an alert route. **Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.**

List alert routing rules. **Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.**

Creates a new alert routing rule from provided data. **Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.**

Retrieves a specific alert routing rule by id. **Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.**

Update a specific alert routing rule by id. **Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.**

List alert urgencies

Creates a new alert urgency from provided data

Retrieves a specific alert urgency by id

Update a specific alert urgency by id

List alert sources

Creates a new alert source from provided data

Retrieves a specific alert source by id

Update a specific alert source by id

List incident alerts

Attach alerts to an incident from provided data

List alerts

Creates a new alert from provided data

Retrieves a specific alert by id

Updates an alert

List Catalog Entities

Creates a new Catalog Entity from provided data

Retrieves a specific Catalog Entity by id

Update a specific Catalog Entity by id

**Deprecated:** This endpoint is deprecated, please use `include=fields` on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to retrieve field values instead. List Catalog Entity Properties.

**Deprecated:** This endpoint is deprecated, please use the `fields` attribute on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to set field values instead. Creates a new Catalog Entity Property from provided data.

**Deprecated:** This endpoint is deprecated, please use `include=fields` on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to retrieve field values instead. Retrieves a specific Catalog Entity Property by id.

**Deprecated:** This endpoint is deprecated, please use the `fields` attribute on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to set field values instead. Update a specific Catalog Entity Property by id.

List Catalog Properties - returns catalog_properties type

Creates a new Catalog Property - returns catalog_properties type

Retrieves a specific Catalog Property by id - returns catalog_properties type

Update a specific catalog_property by id - returns catalog_properties type

List catalogs

Creates a new catalog from provided data

Retrieves a specific catalog by id

Update a specific catalog by id

List causes

Creates a new cause from provided data

Retrieves a specific cause by id

Update a specific cause by id

[DEPRECATED] Use form field endpoints instead. Retrieves a specific custom field option by id

[DEPRECATED] Use form field endpoints instead. Update a specific custom field option by id

[DEPRECATED] Use form field endpoints instead. List Custom fields

[DEPRECATED] Use form field endpoints instead. Creates a new custom field from provided data

Retrieves a specific custom_field by id

[DEPRECATED] Use form field endpoints instead. Update a specific custom field by id

List custom forms

Creates a new custom form from provided data

Retrieves a specific custom form by id

Update a specific custom form by id

Retrieves a specific dashboard panel by id

Update a specific dashboard panel by id

List dashboards

Creates a new dashboard from provided data

Retrieves a specific dashboard by id

Update a specific dashboard by id

List environments

Creates a new environment from provided data

Retrieves a specific environment by id

Update a specific environment by id

List escalation policies

Creates a new escalation policy from provided data

Retrieves a specific escalation policy by id

Update a specific escalation policy by id

List escalation levels

Creates a new escalation level from provided data

List escalation levels

Creates a new escalation level from provided data

Retrieves a specific escalation level by id

Update a specific escalation level by id

List escalation paths

Creates a new escalation path from provided data

Retrieves a specific escalation path by id

Update a specific escalation path by id

List form_field_options

Creates a new form_field_option from provided data

Retrieves a specific form_field_option by id

Update a specific form_field_option by id

Retrieves a specific form_field_placement_condition by id

Update a specific form_field_placement_condition by id

Retrieves a specific form_field_placement by id

Update a specific form_field_placement by id

List form_fields

Creates a new form_field from provided data

Retrieves a specific form_field by id

Update a specific form_field by id

Retrieves a specific form_set_condition by id

Update a specific form_set_condition by id

List form_sets. Without `filter[resource_type]`, returns incident form sets and, when Problem Management is enabled, problem form sets. Pass `filter[resource_type]=incident` to list only incident form sets.

Creates a new form_set from provided data

Retrieves a specific form_set by id

Update a specific form_set by id

List functionalities

Creates a new functionality from provided data

Retrieves a specific functionality by id

Update a specific functionality by id

Get functionality incidents chart

Get functionality uptime chart

List workflow tasks

Creates a new workflow task from provided data

Retrieves a specific workflow_task by id

Update a specific workflow task by id

List workflow form field conditions

Creates a new workflow form field condition from provided data

Retrieves a specific workflow form field condition by id

Update a specific workflow form field condition by id

List workflow groups

Creates a new workflow group from provided data

Retrieves a specific workflow group by id

Update a specific workflow group by id

List workflow runs

Creates a new workflow run from provided data

List workflows

Creates a new workflow from provided data

Retrieves a specific workflow by id

Update a specific workflow by id

List heartbeats

Creates a new heartbeat from provided data

Retrieves a specific heartbeat by id

Update a specific heartbeat by id

List incident action items

Creates a new action item from provided data

Retrieves a specific incident_action_item by id

Update a specific incident action item by id

List all action items for an organization

[DEPRECATED] Use form field endpoints instead. List incident custom field selections

[DEPRECATED] Use form field endpoints instead. Creates a new incident custom field selection from provided data

[DEPRECATED] Use form field endpoints instead. Retrieves a specific incident custom field selection by id

[DEPRECATED] Use form field endpoints instead. Update a specific incident custom field selection by id

List incident events

Creates a new event from provided data

List incident form field selections

Creates a new incident form field selection from provided data

Retrieves a specific incident form field selection by id

Update a specific incident form field selection by id

Retrieves a specific incident retrospective step by id

Update a specific incident retrospective step by id

Retrieves a specific incident_sub_status by id

Update a specific incident_sub_status by id

List incident types

Creates a new incident_type from provided data

Retrieves a specific incident_type by id

Update a specific incident_type by id

List Live Call Routers

Creates a new Live Call Router from provided data

Retrieves a specific Live Call Router by id

Update a specific Live Call Router by id

List all meeting recording sessions for an incident. Returns recordings sorted by session number. Each recording represents one bot session with its own transcript, status, and metadata.

List meeting recordings across the organization. Returns the current user's standalone recordings plus incident-backed recordings the user can access. Supports filtering by status, platform, and created_by.

Retrieve a single meeting recording session including its status, duration, speaker count, word count, and transcript summary.

Search Rootly Observability logs with the Logs explorer query syntax (`service:`, `severity:`, `index:`, `trace_id:`, `@attribute:value`, `OR` inside field groups, `-` negation, `*` prefix, free text). Rows are newest first, clipped and redacted. `meta.query` and `meta.window` echo the effective query and window. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 `unsupported_api_key`) or an OAuth token with the `obs.logs:read` (or `all`) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

List log patterns (clustered log templates) with counts against the previous window of the same length. Only `service:`, `severity:` and `pattern:` filters apply; others are echoed in `meta.ignored_filters`. Each pattern's `logs_query` drills into matching rows with `GET /v1/observability/logs`; it is omitted when that query would exceed the `/logs` length or clause limits. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 `unsupported_api_key`) or an OAuth token with the `obs.logs:read` (or `all`) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

Count logs matching a Logs explorer query, grouped by `service`, `index`, `severity` or an attribute key (`@http.status_code`). Answers questions like "errors per service in the last 6h" (`filter[query]=severity:error`, `filter[from]=now-6h`, `group_by=service`). Values are ordered by count, largest first; `meta.total` counts every matching log, and each value's `logs_query` drills into its rows with `GET /v1/observability/logs` (`null` for a blank value, which the query syntax cannot select, or when the drill-down would exceed the query limits: 512 characters or 20 clauses). A log can carry an attribute key more than once (log, resource and scope attributes), so attribute counts can add up to more than `meta.total`; when logs match but none have the attribute, `data` is empty and `meta.warnings` has code attribute_missing. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 `unsupported_api_key`) or an OAuth token with the `obs.logs:read` (or `all`) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

List On-Call Roles

Creates a new On-Call Role from provided data

Retrieves a specific On-Call Role by id

Update a specific On-Call Role by id

List shadow shifts for schedule

Creates a new on call shadow configuration from provided data

Retrieves a specific On Call Shadow configuration by ID

Update a specific on call shadow configuration by id

List override shifts

Creates a new override shift from provided data. If any existing override shifts overlap with the specified time range, they will be automatically deleted and replaced by the new override. This endpoint is idempotent: re-sending an identical override (same user and same start/end time) returns the existing override with a 200 status and does not recreate it.

Retrieves a specific override shift by id

Update a specific override shift by id

Retrieves a specific playbook_task by id

Update a specific playbook task by id

List playbooks

Creates a new playbook from provided data

Retrieves a specific playbook by id

Update a specific playbook by id

List pulses

Creates a new pulse from provided data

Retrieves a specific pulse by id

Update a specific pulse by id

Retrieves a specific Retrospective Process Group by id

Update a specific Retrospective Process Group by id

List retrospective processes

Creates a new retrospective process from provided data

Retrieves a specific retrospective process by id

Updates a specific retrospective process by id

Retrieves a specific retrospective step by id

Update a specific retrospective step by id

List schedule rotation active days

Creates a new schedule rotation active day from provided data

List schedule rotation users

Creates a new schedule rotation user from provided data

List schedule rotations

Creates a new schedule rotation from provided data

Retrieves a specific schedule rotation by id

Update a specific schedule rotation by id

List schedules

Creates a new schedule from provided data

Retrieves a specific schedule by id

Updates a specific schedule by id

List services

Creates a new service from provided data

Retrieves a specific service by id

Update a specific service by id

Get service incidents chart

Get service uptime chart

List severities

Creates a new severity from provided data

Retrieves a specific severity by id

Update a specific severity by id

List active shift coverage requests for a schedule.

Retrieves a specific shift coverage request.

List status page templates

Creates a new template from provided data

Retrieves a specific status_page_template by id

Update a specific template event by id

List status pages

Creates a new status page from provided data

Retrieves a specific status page by id

Update a specific status page by id

List Sub-Statuses

Creates a new Sub-Status from provided data

Retrieves a specific Sub-Status by id

Update a specific Sub-Status by id

List teams

Creates a new team from provided data

Retrieves a specific team by id

Update a specific team by id

Get team incidents chart

Retrieves all email addresses for the specified user

Creates a new user email address from provided data

List user notification rules

Creates a new user notification rule from provided data

Retrieves all phone numbers for the specified user

Creates a new user phone number from provided data

List users

Get current user

Retrieves a specific user by id