Understanding Read vs Write Tools - PagerDuty MCP Server

Overview

The PagerDuty MCP Server categorizes all tools as either read-only or write tools. This distinction is crucial for maintaining the safety and integrity of your PagerDuty account.

By default, the MCP server only exposes read-only tools. You must explicitly enable write tools using the --enable-write-tools flag when starting the server.

What Are Read-Only Tools?

Read-only tools are safe operations that only retrieve data from your PagerDuty account. They cannot create, modify, or delete any resources. These tools are ideal for:

Exploring your PagerDuty configuration
Monitoring incident status
Checking on-call schedules
Reviewing historical data
Generating reports

Characteristics of Read-Only Tools

No modifications - Cannot change any data in PagerDuty
Safe to experiment - You can call them repeatedly without risk
No confirmation needed - AI assistants can use them freely
Enabled by default - Available immediately after setup

Safety Annotations

All read-only tools are annotated with these safety hints:

ToolAnnotations(
    readOnlyHint=True,      # Does not modify data
    destructiveHint=False,  # Cannot delete resources
    idempotentHint=True     # Safe to retry
)

These annotations help AI assistants understand that read-only tools are safe to use without explicit user confirmation.

What Are Write Tools?

Write tools are operations that create, modify, or delete resources in your PagerDuty account. These tools perform actions that change your live environment, such as:

Creating incidents or services
Updating team membership
Modifying escalation policies
Deleting resources
Triggering workflows

Characteristics of Write Tools

Modify data - Change resources in your PagerDuty account
Require explicit enabling - Must use --enable-write-tools flag
May need confirmation - AI assistants should confirm destructive actions
Cannot be undone - Some operations are irreversible

Safety Annotations

All write tools are annotated with these safety hints:

ToolAnnotations(
    readOnlyHint=False,     # Can modify data
    destructiveHint=True,   # Potentially dangerous
    idempotentHint=False    # May have different effects on retry
)

These annotations signal to AI assistants that write tools require careful handling and user confirmation before execution.

Enabling Write Tools

To enable write tools, you must start the PagerDuty MCP Server with the --enable-write-tools flag:

{
  "mcpServers": {
    "pagerduty-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pagerduty-mcp", "--enable-write-tools"],
      "env": {
        "PAGERDUTY_USER_API_KEY": "your-api-key"
      }
    }
  }
}

Only enable write tools when you intend to perform modifications to your PagerDuty account. This helps prevent accidental changes during exploratory sessions.

Complete Tool Lists

Read-Only Tools (46 tools)

These tools are always available and safe to use:

Tool	Area	Description
get_alert_grouping_setting	Alert Grouping	Retrieves a specific alert grouping setting
list_alert_grouping_settings	Alert Grouping	Lists alert grouping settings with filtering
get_alert_from_incident	Incidents	Retrieves a specific alert from an incident
list_alerts_from_incident	Incidents	Lists all alerts for a specific incident
get_change_event	Change Events	Retrieves a specific change event
list_change_events	Change Events	Lists change events with optional filtering
list_incident_change_events	Change Events	Lists change events related to a specific incident
list_service_change_events	Change Events	Lists change events for a specific service
list_escalation_policies	Escalation Policy	Lists escalation policies
get_escalation_policy	Escalation Policy	Retrieves a specific escalation policy
get_event_orchestration	Event Orchestrations	Retrieves a specific event orchestration
get_event_orchestration_global	Event Orchestrations	Gets the global orchestration configuration
get_event_orchestration_router	Event Orchestrations	Gets the router configuration
get_event_orchestration_service	Event Orchestrations	Gets the service orchestration configuration
list_event_orchestrations	Event Orchestrations	Lists event orchestrations
get_incident	Incidents	Retrieves a specific incident
get_outlier_incident	Incidents	Retrieves outlier incident information
get_past_incidents	Incidents	Retrieves past incidents related to a specific incident
get_related_incidents	Incidents	Retrieves related incidents
list_incident_notes	Incidents	Lists all notes for a specific incident
list_incidents	Incidents	Lists incidents
get_incident_workflow	Incident Workflows	Retrieves a specific incident workflow
list_incident_workflows	Incident Workflows	Lists incident workflows
get_log_entry	Log Entries	Retrieves a specific log entry by ID
list_log_entries	Log Entries	Lists all log entries across the account
list_oncalls	On-call	Lists on-call schedules
get_schedule	Schedules	Retrieves a specific schedule
list_schedule_users	Schedules	Lists users in a schedule
list_schedules	Schedules	Lists schedules
get_service	Services	Retrieves a specific service
list_services	Services	Lists services
get_status_page_post	Status Pages	Retrieves details of a status page post
list_status_page_impacts	Status Pages	Lists available impact levels
list_status_page_post_updates	Status Pages	Lists updates for a status page post
list_status_page_severities	Status Pages	Lists available severity levels
list_status_page_statuses	Status Pages	Lists available statuses
list_status_pages	Status Pages	Lists all status pages
get_team	Teams	Retrieves a specific team
list_team_members	Teams	Lists members of a team
list_teams	Teams	Lists teams
get_user_data	Users	Gets the current user’s data
list_users	Users	Lists users in the PagerDuty account

Write Tools (22 tools)

These tools require the --enable-write-tools flag:

Tool	Area	Description	Destructive
create_alert_grouping_setting	Alert Grouping	Creates a new alert grouping setting	No
update_alert_grouping_setting	Alert Grouping	Updates an existing alert grouping setting	No
delete_alert_grouping_setting	Alert Grouping	Deletes an alert grouping setting	Yes
append_event_orchestration_router_rule	Event Orchestrations	Adds a new routing rule	No
update_event_orchestration_router	Event Orchestrations	Updates router configuration	No
add_note_to_incident	Incidents	Adds note to an incident	No
add_responders	Incidents	Adds responders to an incident	No
create_incident	Incidents	Creates a new incident	No
manage_incidents	Incidents	Updates incident status, urgency, or assignment	No
start_incident_workflow	Incident Workflows	Starts a workflow instance for an incident	No
create_schedule	Schedules	Creates a new on-call schedule	No
create_schedule_override	Schedules	Creates an override for a schedule	No
update_schedule	Schedules	Updates an existing schedule	No
create_service	Services	Creates a new service	No
update_service	Services	Updates an existing service	No
create_status_page_post	Status Pages	Creates a new status page post	No
create_status_page_post_update	Status Pages	Adds an update to a status page post	No
add_team_member	Teams	Adds a user to a team	No
create_team	Teams	Creates a new team	No
delete_team	Teams	Deletes a team	Yes
remove_team_member	Teams	Removes a user from a team	No
update_team	Teams	Updates an existing team	No

Most write tools are not destructive—they create or update resources. Only delete operations are truly destructive and cannot be undone.

Best Practices for Using Write Tools

1. Start in Read-Only Mode

When first exploring your PagerDuty configuration or testing the MCP server:

Do not enable write tools initially
Use read-only tools to understand your current state
Only enable write tools when you’re ready to make changes

2. Verify Before Destructive Operations

Before deleting resources:

Review the resource using a read-only tool first
Confirm the resource ID is correct
Understand the impact of deletion (e.g., removing a team affects all members)
Have a rollback plan if the operation can’t be undone

3. Use Specific Identifiers

When modifying resources:

Use exact IDs rather than names when possible
Verify the resource with a get_* tool before updating
Check related resources that might be affected

4. Test in Non-Production First

If you have multiple PagerDuty accounts:

Configure write tools on a test account first
Verify the behavior matches your expectations
Use separate API tokens for production vs. non-production

5. Monitor API Token Permissions

Your User API token inherits your PagerDuty account permissions:

Review your role in PagerDuty Settings
Understand permission limits (especially for Freemium accounts)
Use least-privilege tokens when possible

6. Review AI Assistant Confirmations

Most AI assistants will ask for confirmation before destructive operations:

Read the confirmation prompt carefully
Verify the resource ID in the prompt
Decline if uncertain and investigate further

Safety Architecture

The PagerDuty MCP Server implements a defense-in-depth approach to safety:

Layer 1: Explicit Enablement

Write tools are disabled by default. You must explicitly pass the --enable-write-tools flag to make them available.

Layer 2: Tool Annotations

Each tool is annotated with safety hints that inform the AI assistant:

Read-only tools are marked safe for automatic use
Write tools are flagged as potentially destructive
Idempotent tools can be safely retried

Layer 3: AI Assistant Confirmation

Most AI assistants implement confirmation dialogs for destructive operations based on the destructiveHint annotation.

Layer 4: PagerDuty Permissions

The PagerDuty API enforces permission checks based on your User API token’s role and account type.

Example Use Cases

Read-Only Session: Incident Investigation

# Start server without write tools
uvx pagerduty-mcp

Safe operations:

“Show me all high-urgency incidents from the last 24 hours”
“Who is currently on-call for the database team?”
“List all services with their escalation policies”
“Show me the change events around incident #12345”

Write Session: Incident Response

# Start server with write tools enabled
uvx pagerduty-mcp --enable-write-tools

Available operations:

“Create an incident for the API service”
“Add a note to incident #12345 with our findings”
“Escalate incident #12345 to the next level”
“Create a schedule override for tomorrow”

Hybrid Workflow

Many workflows combine read and write operations:

Read: “Show me all open incidents”
Read: “Get details for incident #12345”
Write: “Add a note to incident #12345: ‘Database failover completed’”
Write: “Resolve incident #12345”

You can restart the MCP server with write tools enabled mid-session if you realize you need to make changes. Your AI assistant will have access to the new tools once the server restarts.

Frequently Asked Questions

Can I selectively enable only some write tools?

No, the --enable-write-tools flag enables all write tools at once. However, the AI assistant will only use tools that are relevant to your request, and will seek confirmation for destructive operations.

What happens if I try to use a write tool without enabling them?

If write tools are not enabled, they won’t be available to the AI assistant. The assistant will inform you that the requested operation isn’t possible with the current configuration and may suggest enabling write tools.

Are write tools dangerous?

Write tools modify your live PagerDuty account, so they should be used carefully. However, most write operations (create, update) are not destructive and can be reversed manually. Only delete operations are truly destructive. The safety annotations help AI assistants handle write tools appropriately.

Can I use different API tokens for read vs. write operations?

You configure a single API token when starting the MCP server. To use different tokens, you would need to run separate server instances. However, it’s generally better to use the --enable-write-tools flag to control access rather than managing multiple tokens.

How do I know which tools are read-only vs. write?

Check the “Read-only” column in the tools table. Tools marked with ✅ are read-only; tools marked with ❌ are write tools. You can also refer to the complete lists on this page.

Next Steps

Tools Overview

Return to the complete tools reference

Security Best Practices

Learn how to securely configure API access

Incident Management Guide

Explore common incident workflows

Configuration Guide

Review MCP server configuration options

Overview

Incidents

Alerts

Services

Schedules & On-Call

Event Orchestrations

Teams

Users

Escalation Policies

Incident Workflows

Change Events

Log Entries

Alert Grouping

Status Pages

​Overview

​What Are Read-Only Tools?

​Characteristics of Read-Only Tools

​Safety Annotations

​What Are Write Tools?

​Characteristics of Write Tools

​Safety Annotations

​Enabling Write Tools

​Complete Tool Lists

​Read-Only Tools (46 tools)

​Write Tools (22 tools)

​Best Practices for Using Write Tools

​1. Start in Read-Only Mode

​2. Verify Before Destructive Operations

​3. Use Specific Identifiers

​4. Test in Non-Production First

​5. Monitor API Token Permissions

​6. Review AI Assistant Confirmations

​Safety Architecture

​Layer 1: Explicit Enablement

​Layer 2: Tool Annotations

​Layer 3: AI Assistant Confirmation

​Layer 4: PagerDuty Permissions

​Example Use Cases

​Read-Only Session: Incident Investigation

​Write Session: Incident Response

​Hybrid Workflow

​Frequently Asked Questions

​Next Steps

Tools Overview

Security Best Practices

Incident Management Guide

Configuration Guide

Build docs developers (and LLMs) love

Overview

What Are Read-Only Tools?

Characteristics of Read-Only Tools

Safety Annotations

What Are Write Tools?

Characteristics of Write Tools

Safety Annotations

Enabling Write Tools

Complete Tool Lists

Read-Only Tools (46 tools)

Write Tools (22 tools)

Best Practices for Using Write Tools

1. Start in Read-Only Mode

2. Verify Before Destructive Operations

3. Use Specific Identifiers

4. Test in Non-Production First

5. Monitor API Token Permissions

6. Review AI Assistant Confirmations

Safety Architecture

Layer 1: Explicit Enablement

Layer 2: Tool Annotations

Layer 3: AI Assistant Confirmation

Layer 4: PagerDuty Permissions

Example Use Cases

Read-Only Session: Incident Investigation

Write Session: Incident Response

Hybrid Workflow

Frequently Asked Questions

Next Steps