PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:187-238 (handler)

  Handler function for the 'get_oncalls' tool. Decorated with @mcp.tool() for MCP registration. Manages input validation, user context, and delegates core logic to oncalls.list_oncalls().

  @mcp.tool()
  def get_oncalls(
      *,
      current_user_context: bool = True,
      schedule_ids: Optional[List[str]] = None,
      user_ids: Optional[List[str]] = None,
      escalation_policy_ids: Optional[List[str]] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
      limit: Optional[int] = None,
      earliest: Optional[bool] = None,
  ) -> Dict[str, Any]:
      """List on-call entries for schedules, policies, or time ranges.
  
      Behavior varies by time parameters:
      1. Without since/until: Returns current on-calls
         Example: get_oncalls(schedule_ids=["SCHEDULE_123"])
      2. With since/until: Returns all on-calls in range
         Example: get_oncalls(schedule_ids=["SCHEDULE_123"], since="2024-03-20T00:00:00Z", until="2024-03-27T00:00:00Z")
  
      Args:
          current_user_context (bool): Use current user's team policies (default: True)
          schedule_ids (List[str]): Filter by schedules (optional)
          user_ids (List[str]): Filter by users (optional, excludes current_user_context)
          escalation_policy_ids (List[str]): Filter by policies (optional)
          since (str): Start of query range in ISO8601 format (default: current datetime)
          until (str): End of query range in ISO8601 format (default: current datetime, max range: 90 days in the future). Cannot be before `since`.
          limit (int): Max results (optional)
          earliest (bool): Only earliest on-call per policy/level/user combo (optional)
      """
      if current_user_context:
          if user_ids is not None:
              raise ValueError(
                  "Cannot specify user_ids when current_user_context is True. See `docs://tools` for more information."
              )
          user_context = users.build_user_context()
          escalation_policy_ids = user_context["escalation_policy_ids"]
      elif not (schedule_ids or user_ids or escalation_policy_ids):
          raise ValueError(
              "When current_user_context is False, must specify at least one of: schedule_ids, user_ids, or escalation_policy_ids. See `docs://tools` for more information."
          )
  
      return oncalls.list_oncalls(
          user_ids=user_ids,
          schedule_ids=schedule_ids,
          escalation_policy_ids=escalation_policy_ids,
          since=since,
          until=until,
          limit=limit,
          earliest=earliest,
      )

• src/pagerduty_mcp_server/oncalls.py:19-77 (helper)

  Core helper function implementing the on-call listing logic: builds API parameters for PagerDuty's /oncalls endpoint, fetches data, parses each on-call entry with parse_oncall, and formats the standard response.

  def list_oncalls(
      *,
      schedule_ids: Optional[List[str]] = None,
      user_ids: Optional[List[str]] = None,
      escalation_policy_ids: Optional[List[str]] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
      limit: Optional[int] = None,
      earliest: Optional[bool] = None,
  ) -> Dict[str, Any]:
      """List the on-call entries during a given time range.
      An oncall-entry contains the user that is on-call for the given schedule, escalation policy, or time range and also includes the schedule and escalation policy that the user is on-call for. Exposed in `get_oncalls`.
  
      Args:
          schedule_ids (List[str]): Return only on-calls for the specified schedule IDs (optional)
          user_ids (List[str]): Return only on-calls for the specified user IDs (optional)
          escalation_policy_ids (List[str]): Return only on-calls for the specified escalation policy IDs (optional)
          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)
          earliest (bool): If True, only returns the earliest on-call for each combination of escalation policy, escalation level, and user. Useful for determining when the "next" on-calls are for a given set of filters. (optional)
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of on-call entries with user, schedule, and escalation policy information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      params = {}
      if schedule_ids:
          params["schedule_ids[]"] = schedule_ids
      if user_ids:
          params["user_ids[]"] = user_ids
      if escalation_policy_ids:
          params["escalation_policy_ids[]"] = escalation_policy_ids
      if since:
          utils.validate_iso8601_timestamp(since, "since")
          params["since"] = since
      if until:
          utils.validate_iso8601_timestamp(until, "until")
          params["until"] = until
      if limit:
          params["limit"] = limit
      if earliest is not None:
          params["earliest"] = earliest
  
      try:
          response = pd_client.list_all(ONCALLS_URL, params=params)
          parsed_response = [parse_oncall(result=result) for result in response]
          return utils.api_response_handler(
              results=parsed_response, resource_name="oncalls"
          )
      except Exception as e:
          utils.handle_api_error(e)