PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:345-369 (handler)

  Handler function for the 'get_teams' MCP tool. Decorated with @mcp.tool() for registration. Dispatches to teams.show_team() or teams.list_teams() based on whether team_id is provided.

  @mcp.tool()
  def get_teams(
      *,
      team_id: Optional[str] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty teams by filters or get details for a specific team ID.
  
      Args:
          team_id (str): The team ID to retrieve (optional, cannot be used with any other filters).
          query (str): Filter teams whose names contain the search query (optional). Not used if `team_id` is provided.
          limit (int): Limit the number of results returned (optional). Not used if `team_id` is provided.
      """
      if team_id is not None:
          disallowed_filters_present = query is not None or limit is not None
          if disallowed_filters_present:
              raise ValueError(
                  "When `team_id` is provided, other filters (like query, limit) cannot be used. See `docs://tools` for more information."
              )
  
          return teams.show_team(team_id=team_id)
  
      return teams.list_teams(query=query, limit=limit)

• src/pagerduty_mcp_server/teams.py:19-52 (helper)

  Helper function list_teams() called by the handler to list teams matching query and limit. Makes API call to /teams, parses responses, and formats output.

  def list_teams(
      *, query: Optional[str] = None, limit: Optional[int] = None
  ) -> Dict[str, Any]:
      """List teams in your PagerDuty account. Exposed as MCP server tool.
  
      Args:
          query (str): Filter teams 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 teams with their configuration and member information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      params = {}
      if query:
          params["query"] = query
      if limit:
          params["limit"] = limit
  
      try:
          response = pd_client.list_all(TEAMS_URL, params=params)
          parsed_response = [parse_team(result=team) for team in response]
          return utils.api_response_handler(
              results=parsed_response, resource_name="teams"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/teams.py:54-87 (helper)

  Helper function show_team() called by the handler to retrieve details for a specific team_id. Makes API call to /teams/{team_id}, parses response, and formats output.

  def show_team(*, team_id: str) -> Dict[str, Any]:
      """Get detailed information about a given team. Exposed as MCP server tool.
  
      Args:
          team_id (str): The ID of the team to get
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single team with detailed configuration and member information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if team_id is None:
          raise ValueError("team_id must be specified")
  
      pd_client = create_client()
  
      try:
          response = pd_client.jget(f"{TEAMS_URL}/{team_id}")
          try:
              team_data = response["team"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch team {team_id}: Response missing 'team' field"
              )
  
          return utils.api_response_handler(
              results=parse_team(result=team_data), resource_name="team"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/server.py:345-369 (registration)

  The @mcp.tool() decorator registers the get_teams function as an MCP tool.

  @mcp.tool()
  def get_teams(
      *,
      team_id: Optional[str] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty teams by filters or get details for a specific team ID.
  
      Args:
          team_id (str): The team ID to retrieve (optional, cannot be used with any other filters).
          query (str): Filter teams whose names contain the search query (optional). Not used if `team_id` is provided.
          limit (int): Limit the number of results returned (optional). Not used if `team_id` is provided.
      """
      if team_id is not None:
          disallowed_filters_present = query is not None or limit is not None
          if disallowed_filters_present:
              raise ValueError(
                  "When `team_id` is provided, other filters (like query, limit) cannot be used. See `docs://tools` for more information."
              )
  
          return teams.show_team(team_id=team_id)
  
      return teams.list_teams(query=query, limit=limit)