> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# PagerDuty

> Connect PagerDuty to Clarion so agents can page your on-call rotation through PagerDuty's Events API v2 during triage.

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.

> **Note:** **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:

| Tool                            | Purpose                                                                                                                                                                                                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp__pagerduty__list_channels` | List channels the workspace has configured (returns `id`  • `name`). The agent calls this first to know which channels exist.                                                                                                                                                                              |
| `mcp__pagerduty__trigger_alert` | Page 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.