Skip to main content
This guide walks you through connecting PagerDuty to Clarion. Once connected, agents can trigger PagerDuty incidents from a skill or workspace prompt whenever they decide — based on what they found during triage — that an on-call human needs to be paged.
Estimated time: 5 minutes. You’ll need permission to add an Events API v2 integration to at least one PagerDuty service.

​
Prerequisites

  • A PagerDuty account with permission to manage services
  • One or more services in PagerDuty configured with the escalation policies you want Clarion to use
  • A Clarion workspace with the PagerDuty integration page open

​
Step 1 — Enable PagerDuty in Clarion

  1. In Clarion, open Integrations and find PagerDuty.
  2. Click Enable PagerDuty.
The integration is now active but won’t deliver anything yet — PagerDuty needs at least one notification channel.

​
Step 2 — Create an Events API v2 integration in PagerDuty

For each service Clarion should be able to page, generate a routing key:
  1. In PagerDuty, open the service you want Clarion to page.
  2. Go to the Integrations tab.
  3. Click Add another integration.
  4. Choose Events API v2 as the integration type.
  5. Give it a recognisable name, for example Clarion — SecOps.
  6. Click Add and copy the Integration Key (also called routing key) that PagerDuty shows you.
Each routing key targets exactly one PagerDuty service and its escalation policy. If you want different paths for different scenarios (e.g. SecOps vs Platform on-call), create one routing key per service.

​
Step 3 — Add the channel in Clarion

  1. Back on the Clarion PagerDuty integration page, click Add channel.
  2. Enter a name that identifies the rotation — for example SecOps on-call.
  3. Paste the routing key from PagerDuty.
  4. Click Add channel.
  5. Use the Send test event button next to the new row to confirm the routing key is valid. Clarion sends a trigger event and immediately resolves it, so the test will briefly appear in PagerDuty before clearing itself.
Repeat for any other services you want to wire up.

​
Step 4 — Reference PagerDuty in a skill or workspace prompt

PagerDuty isn’t a Clarion escalation channel — operators don’t acknowledge pages back into Clarion. Instead, agents call PagerDuty directly when a skill or the workspace system prompt tells them to.
  1. Open a skill (or the workspace system prompt) in Clarion.
  2. Type # in the editor and pick PagerDuty from the channel/notification menu.
  3. The block embeds with no extra configuration — the agent picks which PagerDuty channel to page at runtime, so the same skill works in any workspace that has PagerDuty channels configured.

​
What the agent can do

When the skill runs and the workspace has at least one PagerDuty channel, the agent gets two tools:
ToolPurpose
mcp__pagerduty__list_channelsList channels the workspace has configured (returns id + name). The agent calls this first to know which channels exist.
mcp__pagerduty__trigger_alertPage a specific channel. The agent passes the channel id, a summary (the PagerDuty incident title), and a severity (critical / error / warning / info). Optionally a dedupKey to coalesce repeats, and customDetails to surface structured fields in PagerDuty’s “Custom Details” panel.
The routing key never leaves the Clarion server — the agent only ever sees the channel id. Clarion resolves the id to the routing key when actually calling the PagerDuty Events API.

​
Default approval gating

trigger_alert requires human approval by default because it pages on-call humans. The agent pauses, the configured notification channel pings the operator, and execution resumes once the request is approved. You can change this in Workspace → Tools for mcp__pagerduty__trigger_alert if you want certain skills to page automatically.

​
Severity rules of thumb

  • critical — production is down, someone needs to act in minutes. Routes through PagerDuty’s escalation policy at full urgency.
  • error — urgent but not immediately dangerous. Sensible default for “this is bad, someone should look at it.”
  • warning — action will be needed but not right now. Good for backlog work surfaced during triage.
  • info — FYI; will not page in most PagerDuty service configurations.

​
Coalescing repeat pages with dedupKey

If a skill might trigger more than once for the same underlying condition (e.g. the agent runs again on a recurring alert), pass a stable dedupKey — for instance the alert id, the affected resource ARN, or any identifier that uniquely names the condition. PagerDuty will update the existing incident instead of opening a new one. Omit dedupKey and Clarion generates a key based on the channel and summary, so accidental re-fires inside a single agent run still coalesce.

​
Alert title and details

Clarion automatically rewrites every PagerDuty alert so the on-call responder can act on it without leaving PagerDuty:
  • The incident summary is always prefixed with [Cantina Clarion] regardless of what the agent supplied.
  • The incident’s Custom Details panel always includes a clarion_url field linking back to the source alert in Clarion (or to the workspace if the agent run wasn’t alert-driven).

​
Disconnect

To remove the PagerDuty integration:
  1. In Clarion, open Integrations → PagerDuty.
  2. Remove the individual channels you no longer need, or
  3. Disconnect the whole integration from the integrations list.
Disconnecting deletes the stored routing keys. Re-enabling later means re-adding each channel; the PagerDuty services themselves are unaffected.

​
Troubleshooting

​
”PagerDuty test failed: …”

The routing key was rejected. Common causes:
  • The key was copied with extra whitespace — re-copy from PagerDuty.
  • The integration in PagerDuty is Events API v1 rather than v2. Clarion only supports v2.
  • The PagerDuty service the integration belongs to has been deleted or suspended.