Skip to main content
Tool Name: add_respondersCategory: IncidentsMode: Write (requires --enable-write-tools flag and user-level token)

​
Overview

The add_responders tool allows you to request additional help on an incident by adding responders. You can add individual users or escalation policies. This sends notifications to the requested responders with an optional message.
This tool requires:
  1. Write mode enabled (--enable-write-tools flag)
  2. User-level API token (not account-level)
The authenticated user will be listed as the requester.

​
Parameters

​
incident_id
string
required
The ID of the incident to add responders to.Example: "Q1234567890ABCDE"
​
message
string
required
A message to include with the responder request explaining why they’re needed.Example: "Need database expertise to investigate query performance issues."
​
responder_request_targets
list[ResponderRequestTarget]
required
Array of users or escalation policies to request as responders.
​
responder_request_target
ResponderRequest
required
Individual responder target.
​
id
string
required
The ID of the user or escalation policy.Example: "PXXXXXX"
​
type
string
required
The type of target.Allowed values:
  • user_reference - Request a specific user
  • escalation_policy_reference - Request via escalation policy
Example: "user_reference"

​
Usage Examples

​
Request a specific user

{
  "incident_id": "Q1234567890ABCDE",
  "message": "Need help investigating database performance issues",
  "responder_request_targets": [
    {
      "responder_request_target": {
        "id": "PXXXXXX",
        "type": "user_reference"
      }
    }
  ]
}

​
Request multiple users

{
  "incident_id": "Q1234567890ABCDE",
  "message": "Critical production issue - need database and network teams",
  "responder_request_targets": [
    {
      "responder_request_target": {
        "id": "PXXXXXX",
        "type": "user_reference"
      }
    },
    {
      "responder_request_target": {
        "id": "PYYYYYY",
        "type": "user_reference"
      }
    }
  ]
}

​
Request via escalation policy

{
  "incident_id": "Q1234567890ABCDE",
  "message": "Need security team to review potential breach",
  "responder_request_targets": [
    {
      "responder_request_target": {
        "id": "PZZZZZZ",
        "type": "escalation_policy_reference"
      }
    }
  ]
}

​
Mix users and escalation policies

{
  "incident_id": "Q1234567890ABCDE",
  "message": "Major outage - need all hands on deck",
  "responder_request_targets": [
    {
      "responder_request_target": {
        "id": "PUSER1",
        "type": "user_reference"
      }
    },
    {
      "responder_request_target": {
        "id": "PEPOLICY1",
        "type": "escalation_policy_reference"
      }
    }
  ]
}

​
Response Format

Returns an IncidentResponderRequestResponse object with details about the responder request.
​
requester
UserReference
The user who requested the responders (the authenticated user).
​
id
string
Requester user ID
​
type
string
Always “user_reference”
​
requested_at
datetime
When the responder request was made.
​
message
string
The message that was included with the request.
​
responder_request_targets
list[dict]
The users or escalation policies that were requested to respond.

​
Common Errors

Account-level token usedIf using an account-level API token:
Cannot add responders with account level auth. Please provide a user token.
Solution: Configure the MCP server with a user-level API token instead of an account-level token. See API Authentication.
Write mode not enabled
Write operations are disabled. Enable with --enable-write-tools flag.
Solution: Restart the MCP server with the --enable-write-tools flag.
Incident not found
404 Not Found: Incident not found
Solution: Verify the incident ID is correct and accessible.
Invalid responder ID
400 Bad Request: User or escalation policy not found
Solution: Verify the user or escalation policy ID is correct using list_users or list_escalation_policies.

​
Best Practices

When to add responders:
  • Specialized expertise needed - Issue requires domain knowledge you don’t have
  • Escalating severity - Impact is larger than initially assessed
  • Time-sensitive issues - Need more hands to resolve faster
  • Knowledge gap - Need someone familiar with the affected system
  • Spreading workload - Original responder is overloaded
Writing effective responder messages:
  • Be specific about why they’re needed
  • Summarize the current situation
  • Indicate urgency level
  • Mention what’s been tried already
Example message:
"Database queries timing out. Tried restarting app servers without effect. 
Need DBA help to investigate query performance and connection pool.
Affecting 30% of production traffic."

manage_incidents

Update incident assignment

add_note_to_incident

Document why responders were added

list_users

Find user IDs

list_escalation_policies

Find escalation policy IDs

​
Source Reference

Function: add_responders in pagerduty_mcp/tools/incidents.py:176 Models: IncidentResponderRequest, IncidentResponderRequestResponse in pagerduty_mcp/models/incidents.py

Build docs developers (and LLMs) love

Get started for freeTalk to us