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)