PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:97-179 (handler)

  Primary handler and registration for the get_incidents tool via @mcp.tool(). Handles input validation, user context, and delegates to incidents.list_incidents() or incidents.show_incident().

  @mcp.tool()
  def get_incidents(
      *,
      incident_id: Optional[str] = None,
      current_user_context: bool = True,
      service_ids: Optional[List[str]] = None,
      team_ids: Optional[List[str]] = None,
      statuses: Optional[List[str]] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
      limit: Optional[int] = None,
      include_past_incidents: Optional[bool] = False,
      include_related_incidents: Optional[bool] = False,
      include_notes: Optional[bool] = False,
  ) -> Dict[str, Any]:
      """Get PagerDuty incidents by filters or get details for a specific incident ID or number.
  
      Args:
          incident_id (str): The incident ID or number to retrieve (optional, cannot be used with any other filters).
          current_user_context (bool): Filter by current user's context (default: True). Not used if `incident_id` is provided.
          service_ids (List[str]): Filter by services (optional, excludes current_user_context). Not used if `incident_id` is provided.
          team_ids (List[str]): Filter by teams (optional, excludes current_user_context). Not used if `incident_id` is provided.
          statuses (List[str]): Filter by status (optional). Not used if `incident_id` is provided. Must be input as a list of strings, valid values are `["triggered", "acknowledged", "resolved"]`.
          since (str): Start of query range in ISO8601 format (default range: 1 month, max range: 6 months). Not used if `incident_id` is provided.
          until (str): End of query range in ISO8601 format (default range: 1 month, max range: 6 months). Not used if `incident_id` is provided.
          limit (int): Max results (optional). Not used if `incident_id` is provided.
          include_past_incidents (Optional[bool]): If True and `incident_id` is provided, includes similar past incidents
              in the response. Defaults to False. Cannot be used without `incident_id`.
          include_related_incidents (Optional[bool]): If True and `incident_id` is provided, includes related incidents
              impacting other services/responders in the response. Defaults to False. Cannot be used without `incident_id`.
          include_notes (Optional[bool]): If True, includes notes for each incident in the response. Defaults to False.
      """
      if incident_id is not None:
          disallowed_filters_present = (
              service_ids is not None
              or team_ids is not None
              or statuses is not None
              or since is not None
              or until is not None
              or limit is not None
          )
          if disallowed_filters_present:
              raise ValueError(
                  "When `incident_id` is provided, other filters (like service_ids, team_ids, statuses, etc.) cannot be used. See `docs://tools` for more information."
              )
  
          incident_response = incidents.show_incident(
              incident_id=incident_id,
              include_past_incidents=include_past_incidents,
              include_related_incidents=include_related_incidents,
              include_notes=include_notes,
          )
  
          return incident_response
  
      if include_past_incidents or include_related_incidents or include_notes:
          raise ValueError(
              "`include_past_incidents`, `include_related_incidents`, and `include_notes` can only be used when a specific `incident_id` is provided. See `docs://tools` for more information."
          )
  
      if current_user_context:
          if service_ids is not None or team_ids is not None:
              raise ValueError(
                  "Cannot specify service_ids or team_ids when current_user_context is True. See `docs://tools` for more information."
              )
          user_context = users.build_user_context()
          team_ids = user_context["team_ids"]
          service_ids = user_context["service_ids"]
      elif not (service_ids or team_ids):
          raise ValueError(
              "Must specify at least service_ids or team_ids when current_user_context is False. See `docs://tools` for more information."
          )
  
      incidents_response = incidents.list_incidents(
          service_ids=service_ids,
          team_ids=team_ids,
          statuses=statuses,
          since=since,
          until=until,
          limit=limit,
      )
  
      return incidents_response

• src/pagerduty_mcp_server/incidents.py:27-108 (helper)

  Core helper function for listing incidents with filtering, API calls to PagerDuty, parsing, and metadata calculation. Called by get_incidents handler.

  def list_incidents(
      *,
      service_ids: Optional[List[str]] = None,
      team_ids: Optional[List[str]] = None,
      statuses: Optional[List[str]] = None,
      urgencies: Optional[List[str]] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """List PagerDuty incidents based on specified filters. Exposed in `get_incidents`.
  
      Args:
          service_ids (List[str]): List of PagerDuty service IDs to filter by (optional)
          team_ids (List[str]): List of PagerDuty team IDs to filter by (optional)
          statuses (List[str]): List of status values to filter by (optional). Valid values are:
              - 'triggered' - The incident is currently active (included by default)
              - 'acknowledged' - The incident has been acknowledged by a user (included by default)
              - 'resolved' - The incident has been resolved (included by default)
              Defaults to ['triggered', 'acknowledged', 'resolved'] if not specified.
          urgencies (List[str]): List of urgency values to filter by (optional). Valid values are:
              - 'high' - High urgency incidents (included by default)
              - 'low' - Low urgency incidents (included by default)
              Defaults to ['high', 'low'] if not specified.
          since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago
          until (str): End of date range in ISO8601 format (optional). Default is now
          limit (int): Limit the number of results returned (optional)
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of incidents with additional metadata about status counts and autoresolve counts.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
      pd_client = create_client()
  
      if statuses is None:
          statuses = DEFAULT_STATUSES
      else:
          invalid_statuses = [s for s in statuses if s not in VALID_STATUSES]
          if invalid_statuses:
              raise ValueError(
                  f"Invalid status values: {invalid_statuses}. Valid values are: {VALID_STATUSES}"
              )
  
      if urgencies is None:
          urgencies = DEFAULT_URGENCIES
      else:
          invalid_urgencies = [u for u in urgencies if u not in VALID_URGENCIES]
          if invalid_urgencies:
              raise ValueError(
                  f"Invalid urgency values: {invalid_urgencies}. Valid values are: {VALID_URGENCIES}"
              )
  
      params = {"statuses": statuses, "urgencies": urgencies}
      if service_ids:
          params["service_ids"] = service_ids
      if team_ids:
          params["team_ids"] = team_ids
      if since is not None:
          utils.validate_iso8601_timestamp(since, "since")
          params["since"] = since
      if until is not None:
          utils.validate_iso8601_timestamp(until, "until")
          params["until"] = until
      if limit:
          params["limit"] = limit
  
      try:
          response = pd_client.list_all(INCIDENTS_URL, params=params)
          metadata = _calculate_incident_metadata(response)
          parsed_response = [parse_incident(result=result) for result in response]
  
          return utils.api_response_handler(
              results=parsed_response,
              resource_name="incidents",
              additional_metadata=metadata,
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/incidents.py:110-212 (helper)

  Core helper function for showing a single incident details, optionally fetching past incidents, related incidents, and notes. Called by get_incidents handler.

  def show_incident(
      *,
      incident_id: str,
      include_past_incidents: Optional[bool] = False,
      include_related_incidents: Optional[bool] = False,
      include_notes: Optional[bool] = False,
  ) -> Dict[str, Any]:
      """Get detailed information about a given incident. Exposed as MCP server tool.
  
      Args:
          incident_id (str): The ID or number of the incident to get
          include_past_incidents (Optional[bool]): If True, includes similar past incidents. Defaults to False.
          include_related_incidents (Optional[bool]): If True, includes related incidents. Defaults to False.
          include_notes (Optional[bool]): If True, includes notes for the incident. Defaults to False.
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single incident in the standard format.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not incident_id:
          raise ValueError("incident_id cannot be empty")
  
      pd_client = create_client()
      params = {"include[]": "body"}
  
      try:
          incident_metadata = {}
  
          response = pd_client.jget(f"{INCIDENTS_URL}/{incident_id}", params=params)
          try:
              incident_data = response["incident"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch or process incident {incident_id}: 'incident'"
              )
  
          parsed_main_incident = parse_incident(result=incident_data)
  
          if include_past_incidents:
              try:
                  past_incidents_response = _list_past_incidents(incident_id=incident_id)
                  if past_incidents_response and past_incidents_response.get("incidents"):
                      parsed_main_incident["past_incidents"] = past_incidents_response[
                          "incidents"
                      ]
  
                  if parsed_main_incident.get("past_incidents"):
                      incident_metadata["past_incidents_count"] = len(
                          parsed_main_incident["past_incidents"]
                      )
              except Exception as e_past:
                  logger.error(
                      f"Error fetching past incidents for {incident_id}: {e_past}"
                  )
  
          if include_related_incidents:
              try:
                  related_incidents_response = _list_related_incidents(
                      incident_id=incident_id
                  )
                  if related_incidents_response and related_incidents_response.get(
                      "incidents"
                  ):
                      parsed_main_incident["related_incidents"] = (
                          related_incidents_response["incidents"]
                      )
  
                  if parsed_main_incident.get("related_incidents"):
                      incident_metadata["related_incidents_count"] = len(
                          parsed_main_incident["related_incidents"]
                      )
              except Exception as e_related:
                  logger.error(
                      f"Error fetching related incidents for {incident_id}: {e_related}"
                  )
  
          if include_notes:
              try:
                  notes_response = _list_notes(incident_id=incident_id)
                  if notes_response and notes_response.get("notes"):
                      parsed_main_incident["notes"] = notes_response["notes"]
  
                  if parsed_main_incident.get("notes"):
                      incident_metadata["notes_count"] = len(
                          parsed_main_incident["notes"]
                      )
              except Exception as e_notes:
                  logger.error(
                      f"Error fetching notes for incident {incident_id}: {e_notes}"
                  )
  
          return utils.api_response_handler(
              results=parsed_main_incident,
              resource_name="incident",
              additional_metadata=incident_metadata,
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/server.py:98-128 (schema)

  Input schema defined by function parameters and docstring in the handler.

  def get_incidents(
      *,
      incident_id: Optional[str] = None,
      current_user_context: bool = True,
      service_ids: Optional[List[str]] = None,
      team_ids: Optional[List[str]] = None,
      statuses: Optional[List[str]] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
      limit: Optional[int] = None,
      include_past_incidents: Optional[bool] = False,
      include_related_incidents: Optional[bool] = False,
      include_notes: Optional[bool] = False,
  ) -> Dict[str, Any]:
      """Get PagerDuty incidents by filters or get details for a specific incident ID or number.
  
      Args:
          incident_id (str): The incident ID or number to retrieve (optional, cannot be used with any other filters).
          current_user_context (bool): Filter by current user's context (default: True). Not used if `incident_id` is provided.
          service_ids (List[str]): Filter by services (optional, excludes current_user_context). Not used if `incident_id` is provided.
          team_ids (List[str]): Filter by teams (optional, excludes current_user_context). Not used if `incident_id` is provided.
          statuses (List[str]): Filter by status (optional). Not used if `incident_id` is provided. Must be input as a list of strings, valid values are `["triggered", "acknowledged", "resolved"]`.
          since (str): Start of query range in ISO8601 format (default range: 1 month, max range: 6 months). Not used if `incident_id` is provided.
          until (str): End of query range in ISO8601 format (default range: 1 month, max range: 6 months). Not used if `incident_id` is provided.
          limit (int): Max results (optional). Not used if `incident_id` is provided.
          include_past_incidents (Optional[bool]): If True and `incident_id` is provided, includes similar past incidents
              in the response. Defaults to False. Cannot be used without `incident_id`.
          include_related_incidents (Optional[bool]): If True and `incident_id` is provided, includes related incidents
              impacting other services/responders in the response. Defaults to False. Cannot be used without `incident_id`.
          include_notes (Optional[bool]): If True, includes notes for each incident in the response. Defaults to False.
      """