PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:377-418 (handler)

  Primary handler for the 'get_users' tool. Decorated with @mcp.tool() for registration. Validates parameters, applies current user context if specified, and delegates to helper functions users.show_user() or users.list_users().

  def get_users(
      *,
      user_id: Optional[str] = None,
      current_user_context: bool = True,
      team_ids: Optional[List[str]] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty users by filters or get details for a specific user ID.
  
      Args:
          user_id (str): The user ID to retrieve (optional, cannot be used with any other filters).
          current_user_context (bool): Use current user's team IDs to filter (default: True). Not used if `user_id` is provided.
          team_ids (List[str]): Filter results to only users assigned to teams with the given IDs (optional, cannot be used with current_user_context). Not used if `user_id` is provided.
          query (str): Filter users whose names contain the search query (optional). Not used if `user_id` is provided.
          limit (int): Limit the number of results (optional). Not used if `user_id` is provided.
      """
      if user_id is not None:
          disallowed_filters_present = (
              team_ids is not None or query is not None or limit is not None
          )
          if disallowed_filters_present:
              raise ValueError(
                  "When `user_id` is provided, other filters (like team_ids, query, limit) cannot be used. See `docs://tools` for more information."
              )
  
          return users.show_user(user_id=user_id)
  
      if current_user_context:
          if team_ids is not None:
              raise ValueError(
                  "Cannot specify 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"]
      elif not team_ids:
          raise ValueError(
              "Must specify at least team_ids when current_user_context is False. See `docs://tools` for more information."
          )
  
      return users.list_users(team_ids=team_ids, query=query, limit=limit)

• src/pagerduty_mcp_server/users.py:75-115 (helper)

  Helper function called by get_users for listing multiple users with filtering by team_ids, query, and limit. Interacts with PagerDuty API.

  def list_users(
      *,
      team_ids: Optional[List[str]] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """List users in PagerDuty. Exposed as MCP server tool.
  
      Args:
          team_ids (List[str]): Filter results to only users assigned to teams with the given IDs (optional)
          query (str): Filter users whose names contain the search query (optional)
          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 users with their profile information including teams, contact methods, and notification rules.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      params = {}
  
      if team_ids:
          params["team_ids[]"] = team_ids
      if query:
          params["query"] = query
      if limit:
          params["limit"] = limit
  
      try:
          response = pd_client.list_all(USERS_URL, params=params)
          parsed_response = [parse_user(result=result) for result in response]
          return utils.api_response_handler(
              results=parsed_response, resource_name="users"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/users.py:117-150 (helper)

  Helper function called by get_users for retrieving a single user by ID. Interacts with PagerDuty API.

  def show_user(*, user_id: str) -> Dict[str, Any]:
      """Get detailed information about a given user. Exposed as MCP server tool.
  
      Args:
          user_id (str): The ID of the user to fetch
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single user with detailed profile information including teams, contact methods, and notification rules.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not user_id:
          raise ValueError("User ID is required")
  
      pd_client = create_client()
  
      try:
          response = pd_client.jget(f"{USERS_URL}/{user_id}")
          try:
              user_data = response["user"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch user {user_id}: Response missing 'user' field"
              )
  
          return utils.api_response_handler(
              results=parse_user(result=user_data), resource_name="user"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/users.py:15-68 (helper)

  Helper function used by get_users (and other tools) to build current user's context (team_ids etc.) for filtering.

  def build_user_context() -> Dict[str, Any]:
      """Validate and build the current user's context. Exposed as MCP server tool.
  
      See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain the current user's context in the format defined in the "build_user_context" section of `tools.md`.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
      try:
          user = _show_current_user()
          if not user:
              raise ValueError("Failed to get current user data")
  
          context = {
              "user_id": str(user.get("id", "")).strip(),
              "name": user.get("name", ""),
              "email": user.get("email", ""),
              "team_ids": [],
              "service_ids": [],
              "escalation_policy_ids": [],
          }
  
          if not context["user_id"]:
              raise ValueError("Invalid user data: missing or empty user ID")
  
          team_ids = teams.fetch_team_ids(user=user)
          context["team_ids"] = [
              str(tid).strip() for tid in team_ids if tid and str(tid).strip()
          ]
  
          if context["team_ids"]:
              service_ids = services.fetch_service_ids(team_ids=context["team_ids"])
              context["service_ids"] = [
                  str(sid).strip() for sid in service_ids if sid and str(sid).strip()
              ]
  
          escalation_policy_ids = escalation_policies.fetch_escalation_policy_ids(
              user_id=context["user_id"]
          )
          context["escalation_policy_ids"] = [
              str(epid).strip()
              for epid in escalation_policy_ids
              if epid and str(epid).strip()
          ]
  
          return context
  
      except Exception as e:
          utils.handle_api_error(e)