incidentrelay-mcp

An MCP server for IncidentRelay — self-hosted on-call scheduling, alert routing, and incident management.

It exposes IncidentRelay's entire REST API (279 operations) to MCP clients (Claude Desktop, Claude Code, Cursor, …) through two layers:

• 3 gateway tools that make every operation reachable, driven by the server's own OpenAPI document.
• 25 curated tools that wrap the common on-call workflows (acknowledge/ resolve alerts, incidents, on-call schedule, silences, maintenance windows) with typed, ergonomic inputs.

The server never modifies IncidentRelay. It is a pure REST client that authenticates with a bearer token you provide.

Run

No install needed — run it with npx (Node.js ≥ 20):

# from GitHub (works today)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y github:NikGariel/IncidentRelay-mcp

# from npm (after the package is published)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y incidentrelay-mcp

npx builds the package automatically on first run (a prepare script compiles TypeScript), so no separate build step is required.

From source

npm install   # runs the build via the prepare script
npm start

Configure

The server needs the IncidentRelay base URL and a bearer token (a JWT access token or a personal API token created in IncidentRelay under Profile → API tokens, with the scopes you want to allow).

Setting	Env	Flag	Required	Default
Base URL	IR_BASE_URL	--base-url	yes	—
Bearer token	IR_TOKEN	--token	yes¹	—
Transport	IR_TRANSPORT	--transport	no	stdio
HTTP port	IR_PORT	--port	no	3000
HTTP host	IR_HOST	--host	no	127.0.0.1
Read-only	IR_READONLY	--readonly	no	false
Request timeout (ms)	IR_TIMEOUT_MS	—	no	30000
OpenAPI URL override	IR_OPENAPI_URL	—	no	{base}/api/openapi.json
TLS verification	IR_VERIFY_TLS	—	no	true

¹ The token is optional only if you never call write operations.

At startup the server fetches {IR_BASE_URL}/api/openapi.json (a public endpoint) to build its operation catalog, so it always matches the deployed IncidentRelay version. If that fetch fails, it falls back to a bundled snapshot and logs a warning.

Use with Claude Desktop / Claude Code (stdio)

Add to your MCP client config (e.g. claude_desktop_config.json).

Recommended — run the prebuilt binary directly (starts in <0.5s, so it never hits the client's startup timeout):

{
  "mcpServers": {
    "incidentrelay": {
      "command": "node",
      "args": ["/absolute/path/to/incidentrelay-mcp/dist/index.js"],
      "env": {
        "IR_BASE_URL": "https://incidentrelay.example.com",
        "IR_TOKEN": "<personal-api-token>"
      }
    }
  }
}

Build it once with npm install && npm run build (or npm install -g .).

Alternative — npx. Once published to npm:

{ "command": "npx", "args": ["-y", "incidentrelay-mcp"], "env": { "…": "…" } }

⚠️ Avoid npx -y github:… in a client config: its first run clones the repo, installs dependencies, and compiles TypeScript, which can exceed an MCP client's ~30s connection timeout on a cold cache. Use the prebuilt binary (or the npm form after publishing) for a client that spawns the server on demand.

The server itself starts instantly regardless of network: it loads a bundled OpenAPI snapshot synchronously, then refreshes the catalog from the live server in the background.

Use over HTTP (Streamable HTTP)

IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=... \
  npx -y github:NikGariel/IncidentRelay-mcp --transport http --port 3000
# serves MCP at http://127.0.0.1:3000/mcp

The HTTP transport is stateless (one server per request), binds to 127.0.0.1 by default, and has DNS-rebinding protection enabled.

Tools

Gateway (cover all 279 operations)

Tool	Purpose
ir_list_operations	Search/list the API catalog by query, tag, or method.
ir_describe_operation	Show one operation's params and request-body schema.
ir_call	Execute any operation by operationId (or method+path).

Typical flow: ir_list_operations → ir_describe_operation → ir_call.

Curated (common on-call workflows)

Alerts: ir_list_alerts, ir_get_alert, ir_ack_alert, ir_resolve_alert, ir_comment_alert · Incidents: ir_list_incidents, ir_get_incident, ir_create_incident, ir_add_incident_responder, ir_set_incident_priority · On-call: ir_who_is_on_call, ir_oncall_health, ir_list_rotations, ir_create_rotation_override · Silences: ir_list_silences, ir_create_silence, ir_remove_silence · Maintenance: ir_list_maintenance_windows, ir_create_maintenance_window · Context: ir_list_teams, ir_list_routes, ir_list_channels, ir_whoami · Heartbeats: ir_list_heartbeats, ir_send_heartbeat.

Safety

• Confirm-guard. Destructive operations (DELETE, and paths with disable/remove/delete/reset/regenerate-token/intake-token/ cancel/merge/revoke) do not run unless you pass confirm: true. Without it, the tool returns a dry-run preview.
• Read-only mode. Set IR_READONLY=true to refuse every non-GET operation at the tool layer.
• Token redaction. Bearer tokens are stripped from logs and error output.

Security

IR_VERIFY_TLS=false disables TLS certificate verification for outbound calls to IncidentRelay. This exposes traffic to man-in-the-middle attacks and should only be used on a trusted network. For self-hosted self-signed certificates, prefer adding the server's CA to your trust store (or use a properly-issued certificate) instead of disabling verification. When disabled, the server prints a warning at startup.

Development

npm test          # run the vitest suite
npm run dev       # run from source with tsx
npm run build     # typecheck + emit dist/ + copy the OpenAPI snapshot

Regenerating the bundled OpenAPI snapshot: see scripts/generate-snapshot.md.

Design & plan

• Design spec: docs/superpowers/specs/2026-08-17-incidentrelay-mcp-design.md
• Implementation plan: docs/superpowers/plans/2026-08-17-incidentrelay-mcp.md