PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/schedules.py:101-147 (handler)

  Core handler function that implements the logic to fetch users on call for a PagerDuty schedule using the API, including validation, API call, parsing, and error handling.

  def list_users_oncall(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """List the users on call for a given schedule during the specified time range. Returns a list of users who are or will be on call during the specified period. Exposed as MCP server tool.
  
      Args:
          schedule_id (str): The ID of the schedule to list users on call for
          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
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of users who are on call during the specified time range.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not schedule_id:
          raise ValueError("schedule_id cannot be empty")
  
      pd_client = create_client()
  
      params = {}
      if since:
          utils.validate_iso8601_timestamp(since, "since")
          params["since"] = since
      if until:
          utils.validate_iso8601_timestamp(until, "until")
          params["until"] = until
  
      try:
          response = pd_client.jget(f"{SCHEDULES_URL}/{schedule_id}/users", params=params)
          try:
              users_data = response["users"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch users on call for schedule {schedule_id}: Response missing 'users' field"
              )
  
          return utils.api_response_handler(
              results=[parse_user(result=user) for user in users_data],
              resource_name="users",
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/server.py:275-288 (registration)

  MCP tool registration using @mcp.tool() decorator. Defines the tool schema via parameters and docstring, and delegates execution to the core handler in schedules.py.

  @mcp.tool()
  def list_users_oncall(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """List the users on call for a schedule during the specified time range.
  
      Args:
          schedule_id (str): The ID of the schedule to query
          since (str): Start of query range in ISO8601 format
          until (str): End of query range in ISO8601 format
      """
      return schedules.list_users_oncall(
          schedule_id=schedule_id, since=since, until=until
      )