Skip to main content

incident.io

incident.io is an incident management and on-call platform. This connector covers incidents, alerts, escalations, follow-ups, teams, and the service catalog, and adds the on-call configuration writes that incident.io's own MCP server leaves out: editing escalation paths, editing schedules, and creating schedule overrides.

Relationship to the official incident.io MCP server​

incident.io also runs an official MCP server, listed under Official MCP Servers, so incident.io appears twice in the catalog — once with a By Willow badge (this connector) and once with an Official badge. The two are complementary:

  • Its on-call tools are read-only. If you want an agent to change who gets paged, you need this connector.
  • This connector is built on incident.io's public REST API, so it reaches what that API exposes and nothing more. Their MCP server also surfaces capabilities that do not exist in the public API — AI and investigation features it computes itself — and those cannot be reproduced in a connector.

Run both servers if you want that second group alongside the on-call writes. Their MCP documentation is the current list of what their server offers.

Authentication Types​

incident.io supports 1 authentication method:

  • API Key — A key you create in incident.io, granted named permissions.
    • Pros: Simple setup, per-key permissions, keys can be scoped to specific teams, editable after creation
    • Cons: Shared credential rather than per-user, so incident.io attributes actions to the key rather than the person
note

The public REST API accepts API keys only. The OAuth flow incident.io offers is for connecting to their own hosted MCP server, not their API, so it cannot be used here.

Setting up an API Key​

  1. Log in to incident.io and go to Settings → API keys, then click Add new. You need the Manage API keys permission, and you can only grant permissions you hold yourself.

  2. Give the key a name and select the permissions for the tools you plan to enable — see the table below. incident.io grants permissions, which each bundle several underlying API scopes; hover the scopes badge on a permission in the create dialog to see exactly what it includes.

  3. Optionally scope the write permissions to specific teams. Several of them support this, which is the tightest way to let an agent manage one team's on-call without reaching another team's schedules.

  4. Click Create and copy the token immediately. incident.io shows it once.

  5. In Willow, go to MCP Servers → + Add MCP server, select incident.io, and click + Use.

  6. Open the Setup tab, paste the token under Authentication, and click Save Changes.

Permissions per tool group​

Toolsincident.io permission
All escalation path, escalation, schedule, override, and alert readsView on-call resources (on_call_viewer)
Incident, incident update, follow-up, and team readsView data (viewer)
The same reads, but including private incidents, alerts, and escalationsadd View all incident data (global_access)
Catalog readsView catalog (catalog_viewer)
Update Escalation PathManage on-call resources (on_call_editor)
Update Schedule, Preview Schedule EntriesCreate and update schedules (schedules_editor)
Create Schedule OverrideManage schedule overrides (schedule_overrides_editor)
Respond To EscalationCreate escalations (escalation_creator)
Create IncidentCreate incidents (incident_creator)
Update Incident, Create Follow UpEdit incidents (incident_editor)
tip

Manage schedule overrides covers overrides without granting schedule edits — "create, update, and delete schedule overrides, not schedules". If your only goal is arranging cover, grant that instead of schedules_editor and the destructive full-replace write stays out of reach entirely.

If a key turns out to be missing something, you can edit it in place from Settings → API keys rather than creating a replacement.

Available Tools​

29 tools across nine areas. Three of them write to on-call configuration; the rest read, or act on incidents and escalations.

Escalation paths (3 tools)​

  • List Escalation Paths — GET /v2/escalation_paths. Find a path's ID.
  • Get Escalation Path — GET /v2/escalation_paths/{id}. Returns the full node structure: levels, targets, branching conditions, repeat config, and working hours.
  • Update Escalation Path — PUT /v2/escalation_paths/{id}. Requires id, name, and path. Replaces the entire path with what you send.

Escalations (3 tools)​

  • List Escalations — GET /v2/escalations. The individual pages raised against escalation paths.
  • Get Escalation — GET /v2/escalations/{id}. Includes the transition history: who was paged at each level, when, and how they responded.
  • Respond To Escalation — POST /v2/escalations/{escalation_id}/actions/respond. response is ack, nack, or snooze; snooze also needs snooze_details.snooze_until. Answers a page on behalf of the API key's user; it does not change the path.

Schedules (5 tools)​

  • List Schedules — GET /v2/schedules. Shows who is currently on call and the next handover. Keep page_size at 25 or lower, or incident.io omits the upcoming shifts.
  • Get Schedule — GET /v2/schedules/{id}. Every rotation, future rotation version, layer, handover cadence, user, working interval, and the timezone.
  • Update Schedule — PUT /v2/schedules/{id}. Requires id and schedule. Replaces the schedule's entire configuration, including future rotation versions.
  • Preview Schedule Entries — POST /v2/schedules/{id}/actions/preview_entries. Dry-runs a configuration and returns the shifts it would produce, saving nothing. Window defaults to now through four weeks out.
  • List Schedule Entries — GET /v2/schedule_entries. The real shifts over a window you choose, so you can confirm a change holds beyond the next few days.

Schedule overrides (2 tools)​

  • Create Schedule Override — POST /v2/schedule_overrides. Requires schedule_id, rotation_id, layer_id, start_at, end_at, and user. Additive, and leaves the underlying configuration untouched.
  • List Schedule Overrides — GET /v2/schedule_overrides. Requires schedule_id; optionally narrow by rotation or layer.

Alerts and routing (4 tools)​

  • List Alerts — GET /v2/alerts. Defaults to 25 per page.
  • Get Alert — GET /v2/alerts/{id}. Includes any incidents linked to the alert.
  • List Alert Sources — GET /v2/alert_sources. The integrations and endpoints that can raise alerts.
  • List Alert Routes — GET /v3/alert_routes. Shows which escalation paths and alert sources each route targets — use it to check the blast radius before changing a path.

Incidents (5 tools)​

  • List Incidents — GET /v2/incidents. Sort with sort_by.
  • Get Incident — GET /v2/incidents/{id}. Status, severity, custom fields, role assignments, and timestamps.
  • Create Incident — POST /v2/incidents. Requires visibility (public or private). Set mode to test or tutorial when you are not declaring a real incident. An idempotency_key is generated automatically if you omit one.
  • Update Incident — POST /v2/incidents/{id}/actions/edit. Requires id and notify_incident_channel. Only the fields you supply change.
  • List Incident Updates — GET /v2/incident_updates. The status update history for an incident.

Follow-ups (2 tools)​

  • List Follow Ups — GET /v3/follow_ups. Narrow by incident, assignee team, or incident mode.
  • Create Follow Up — POST /v3/follow_ups. Requires incident_id and title. Descriptions support Markdown.

Teams (2 tools)​

  • List Teams — GET /v3/teams. Source of the team IDs that Update Escalation Path and Update Schedule expect in team_ids.
  • Get Team — GET /v3/teams/{id}. Includes the escalation paths, alert sources, and schedules the team owns.

Catalog (3 tools)​

  • List Catalog Types — GET /v3/catalog_types. Types such as Service or Team.
  • List Catalog Entries — GET /v3/catalog_entries. Requires catalog_type_id. Defaults to 25 per page.
  • Get Catalog Entry — GET /v3/catalog_entries/{id}. Set expand to include backward attribute links as well as forward ones.

Working with the on-call writes​

Update Escalation Path and Update Schedule are full-replace operations: anything you omit from the payload is deleted. Both are classified high risk, so they stay disabled unless you raise the risk level when adding the connector, or enable them yourself afterwards. Two patterns keep them safe once you do.

Change a path or schedule​

Get Escalation Path / Get Schedule   (fetch current state)
→ apply your single change to that payload
→ Preview Schedule Entries           (schedules only — confirm the shifts)
→ Update Escalation Path / Update Schedule
→ Get ... again, or List Schedule Entries   (verify)

Send back every node, rotation, and version you want to keep. For schedules, the way to change who is on call from a future date without disturbing earlier shifts is to leave the current rotation version alone and add another version of the same rotation with effective_from set to an upcoming handover.

Arrange cover, a swap, or time off​

List Schedules → Get Schedule        (get rotation and layer IDs)
→ List Schedule Overrides            (see what cover already exists)
→ Create Schedule Override
→ List Schedule Overrides            (verify)

Prefer this over Update Schedule. Overrides are additive and reversible, and they cannot delete a rotation.

Check the blast radius before changing a path​

List Alert Routes                    (which routes target this path)
→ List Alert Sources                 (what feeds those routes)
→ Get Escalation Path → Update Escalation Path

Troubleshooting​

403 on an escalation path, schedule, or override write​

Cause: The key holds the view permissions but not the matching write permission. A 403 on writes while the reads still work always points here.

Solution: Edit the key in Settings → API keys and add the permission for that tool group from the table above — on_call_editor for escalation paths, schedules_editor for schedules, schedule_overrides_editor for overrides. There is no need to create a replacement key.

403 on a write, with the right permission granted​

Cause: The permission is scoped to specific teams and the resource belongs to a different team. Most of the on-call write permissions can be team-scoped.

Solution: Check which teams the key covers, and use Get Team or Get Schedule to confirm which team owns the resource. Either widen the key to that team or grant the permission at the account level.

Rotations or future versions disappeared after Update Schedule​

Cause: The update replaces the whole configuration. Any rotation or rotation version not included in the payload is deleted.

Solution: Call Get Schedule first and send its full configuration back with only your intended change applied. Use Preview Schedule Entries to confirm the resulting shifts before applying, and reach for Create Schedule Override instead whenever you only need temporary cover.

Alert routes stopped paging the right people​

Cause: An escalation path was replaced without accounting for the alert routes pointing at it.

Solution: Use List Alert Routes to see which routes target the path, then Get Escalation Path and re-apply the change with the full node structure intact.

page_size errors, or list results missing expected fields​

Cause: incident.io requires page_size on some endpoints and changes its response on others. Alerts and catalog entries reject a request without it; schedules only include upcoming shifts on pages of 25 or fewer.

Solution: The connector defaults page_size to 25 for alerts and catalog entries, so leave it unset unless you need a different size. For schedules, keep it at 25 or lower.

An incident was declared twice​

Cause: Create Incident was retried without reusing the original idempotency_key, so incident.io treated the retry as a new incident.

Solution: The connector generates a key when you omit one, which protects a single call but not a retry. Pass your own idempotency_key and reuse the same value when retrying.

Update Incident rejected as an invalid request​

Cause: notify_incident_channel is required on every edit, even one that changes nothing else.

Solution: Always supply it — true posts the update into the incident's Slack channel, false applies it quietly.

Additional Resources​

On this page