Panther MCP Server

Instructions

Implementation Reference

• src/mcp_panther/panther_mcp_core/tools/users.py:17-83 (handler)

  The @mcp_tool decorated handler function implementing the list_users tool. Includes input schema via Annotated Fields with Pydantic validation, fetches users from Panther REST API /users endpoint with pagination support (cursor/limit), handles errors, and returns structured response with success flag, users list, pagination info.

  @mcp_tool(
      annotations={
          "permissions": all_perms(Permission.USER_READ),
          "readOnlyHint": True,
      }
  )
  async def list_users(
      cursor: Annotated[
          str | None,
          Field(description="Optional cursor for pagination from a previous query"),
      ] = None,
      limit: Annotated[
          int,
          Field(
              description="Maximum number of results to return (1-60)",
              ge=1,
              le=60,
          ),
      ] = 60,
  ) -> dict[str, Any]:
      """List all Panther user accounts.
  
      Returns:
          Dict containing:
          - success: Boolean indicating if the query was successful
          - users: List of user accounts if successful
          - total_users: Number of users returned
          - has_next_page: Boolean indicating if more results are available
          - next_cursor: Cursor for fetching the next page of results
          - message: Error message if unsuccessful
      """
      logger.info("Fetching Panther users")
  
      try:
          # Use REST API with pagination support
          params = {"limit": limit}
          if cursor:
              params["cursor"] = cursor
  
          async with get_rest_client() as client:
              result, status = await client.get(
                  "/users", params=params, expected_codes=[200]
              )
  
          if status != 200:
              raise Exception(f"API request failed with status {status}")
  
          users = result.get("results", [])
          next_cursor = result.get("next")
  
          logger.info(f"Successfully retrieved {len(users)} users")
  
          return {
              "success": True,
              "users": users,
              "total_users": len(users),
              "has_next_page": next_cursor is not None,
              "next_cursor": next_cursor,
          }
  
      except Exception as e:
          logger.error(f"Failed to fetch users: {str(e)}")
          return {
              "success": False,
              "message": f"Failed to fetch users: {str(e)}",
          }

• src/mcp_panther/panther_mcp_core/tools/users.py:17-22 (registration)

  The @mcp_tool decorator registers list_users in the tool registry with required permissions (USER_READ) and read-only hint. The registry is triggered by module import in tools/__init__.py and registered to MCP server via register_all_tools in server.py.

  @mcp_tool(
      annotations={
          "permissions": all_perms(Permission.USER_READ),
          "readOnlyHint": True,
      }
  )

• src/mcp_panther/panther_mcp_core/tools/users.py:24-36 (schema)

  Input schema defined using Annotated types and Pydantic Field for cursor (optional pagination string) and limit (1-60 integer). Output is a dict with success, users, total_users, has_next_page, next_cursor or error message.

      cursor: Annotated[
          str | None,
          Field(description="Optional cursor for pagination from a previous query"),
      ] = None,
      limit: Annotated[
          int,
          Field(
              description="Maximum number of results to return (1-60)",
              ge=1,
              le=60,
          ),
      ] = 60,
  ) -> dict[str, Any]: