get_users
Retrieve PagerDuty user details by ID or filter users based on team assignments, search queries, and contextual data for efficient user management.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| current_user_context | No | ||
| limit | No | ||
| query | No | ||
| team_ids | No | ||
| user_id | No |
Implementation Reference
- 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)
- 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)
- 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)
- 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)